Example transactions ¶

This page outlines example roundtrip HTTP transactions conforming to the Eligibility Verification API.

Sample server ¶

For the following examples, assume a Server with a database like:

Driver’s License Number	Last Name	Date of Birth
A1234567	Garcia	1955-08-27
B2345678	Hernandez	1961-01-23

Further, assume the Server validates the eligibility type senior for those individuals age 65 or older.

Usage of JWT in examples ¶

For the purposes of these examples, JWT signing will be done using the simpler, secret-based HMAC SHA-256 (HS256) signing algorithm. This is not appropriate for production as it does not carry the same guarantees as a public-key signing algorithm.

Example JWT header ¶

Although the header will indicate otherwise, for simplification the examples will not show encryption/decryption of the JWT.

The JWT header (both Request and Response) for each of the following examples is:

{
  "alg": "HS256",
  "enc": "RS256",
  "typ": "JWT"
}

Test encoding/decoding ¶

To test JWT encoding/decoding, use the Debugger tool on JWT.IO. Paste in an encoded key to get the decoded output. Or build decoded output to see the corresponding encoded key.

This tool must not be used with real (PII) data.

Examples ¶

1. Eligible senior ¶

This JWT was issued at 2021/09/29 05:30:16 (UTC); the subject (Garcia) is 66 years old.

Request JWT payload ¶

{
  "jti": "0890cce7-25d3-425c-a81b-bc437c2e18a3",
  "iss": "https://calitp.org",
  "iat": 1632893416,
  "agency": "ABC Transit Company",
  "eligibility": [
    "senior"
  ],
  "sub": "A1234567",
  "name": "Garcia"
}

HTTP Request ¶

The preceding header and payload result in the (signed, Base64url-encoded) JWT used in the following Authorization header:

GET /api/eligibility HTTP/1.1
Host: verify.gov
Authorization: Bearer eyJhbGciOiJIUzI1NiIsImVuYyI6IlJTMjU2IiwidHlwIjoiSldUIn0.ey
JqdGkiOiIwODkwY2NlNy0yNWQzLTQyNWMtYTgxYi1iYzQzN2MyZTE4YTMiLCJpc3MiOiJodHRwczovL2
NhbGl0cC5vcmciLCJpYXQiOjE2MzI4OTM0MTYsImFnZW5jeSI6IkFCQyBUcmFuc2l0IENvbXBhbnkiLC
JlbGlnaWJpbGl0eSI6WyJzZW5pb3IiXSwic3ViIjoiQTEyMzQ1NjciLCJuYW1lIjoiR2FyY2lhIn0.sM
VsPU4ByJNR9lADrjlZHeNi1NkBoPdXO50fnCFDDqM

HTTP Response ¶

HTTP/1.1 200 OK
Date: Wed, 29 Sep 2021 05:30:17 GMT
Content-Type: text/plain; charset=UTF-8
Content-Length: 254

eyJhbGciOiJIUzI1NiIsImVuYyI6IlJTMjU2IiwidHlwIjoiSldUIn0.eyJqdGkiOiIwODkwY2NlNy0y
NWQzLTQyNWMtYTgxYi1iYzQzN2MyZTE4YTMiLCJpc3MiOiJodHRwczovL3ZlcmlmeS5nb3YiLCJpYXQi
OjE2MzI4OTM0MTcsImVsaWdpYmlsaXR5IjpbInNlbmlvciJdfQ.tos2vJOO6msv9tMDMT34f95aIRvYj
sHRVUz5621fNlI

Response JWT payload ¶

Base64url-decoding the JWT in the response body yields the following payload:

{
  "jti": "0890cce7-25d3-425c-a81b-bc437c2e18a3",
  "iss": "https://verify.gov",
  "iat": 1632893417,
  "eligibility": [
    "senior"
  ]
}

The presence of the value "senior" in the eligibility array indicates that the Request subject associated with this JWT (Garcia) has been verified for that eligibility.

2. Ineligible senior ¶

This JWT was issued at 2021/09/29 05:30:16 (UTC), meaning the subject (Hernandez) is 60 years old.

Request JWT payload ¶

{
  "jti": "b2bb29dc-6f6a-44a2-83cf-e298123bbbd2",
  "iss": "https://calitp.org",
  "iat": 1632893416,
  "agency": "ABC Transit Company",
  "eligibility": [
    "senior"
  ],
  "sub": "B2345678",
  "name": "Hernandez"
}

HTTP Request ¶

The preceding header and payload result in the (signed, Base64url-encoded) JWT used in the following Authorization header:

GET /api/eligibility HTTP/1.1
Host: verify.gov
Authorization: Bearer eyJhbGciOiJIUzI1NiIsImVuYyI6IlJTMjU2IiwidHlwIjoiSldUIn0.ey
JqdGkiOiJiMmJiMjlkYy02ZjZhLTQ0YTItODNjZi1lMjk4MTIzYmJiZDIiLCJpc3MiOiJodHRwczovL2
NhbGl0cC5vcmciLCJpYXQiOjE2MzI4OTM0MTYsImFnZW5jeSI6IkFCQyBUcmFuc2l0IENvbXBhbnkiLC
JlbGlnaWJpbGl0eSI6WyJzZW5pb3IiXSwic3ViIjoiQjIzNDU2NzgiLCJuYW1lIjoiSGVybmFuZGV6In
0.iY58E7ZYQziQ8ZH7iGSwPGp9S1xbFm6JLXFK0D2E-0w

HTTP Response ¶

HTTP/1.1 200 OK
Date: Wed, 29 Sep 2021 05:30:17 GMT
Content-Type: text/plain; charset=UTF-8
Content-Length: 243

eyJhbGciOiJIUzI1NiIsImVuYyI6IlJTMjU2IiwidHlwIjoiSldUIn0.eyJqdGkiOiJiMmJiMjlkYy02
ZjZhLTQ0YTItODNjZi1lMjk4MTIzYmJiZDIiLCJpc3MiOiJodHRwczovL3ZlcmlmeS5nb3YiLCJpYXQi
OjE2MzI4OTM0MTcsImVsaWdpYmlsaXR5IjpbXX0._hE8UJPYSmQ0q6xymx8UIVF8BrlZry-G82g9ssyP
dO4

Response JWT payload ¶

Base64url-decoding the JWT in the response body yields the following payload:

{
  "jti": "b2bb29dc-6f6a-44a2-83cf-e298123bbbd2",
  "iss": "https://verify.gov",
  "iat": 1632893417,
  "eligibility": []
}

The absence of a value in the eligibility array indicates that the Request subject associated with this JWT (Hernandez) has not been verified for any eligibility.

3. No eligibility data ¶

No data on the subject (Smith) exists in the Server’s database.

*Request JWT payload ¶

{
  "jti": "ef8e9805-bb1b-4f97-903b-6b9ab830d604",
  "iss": "https://calitp.org",
  "iat": 1632893416,
  "agency": "ABC Transit Company",
  "eligibility": [
    "senior"
  ],
  "sub": "C3456789",
  "name": "Smith"
}

HTTP Request ¶

The preceding header and payload result in the (signed, Base64url-encoded) JWT used in the following Authorization header:

GET /api/eligibility HTTP/1.1
Host: verify.gov
Authorization: Bearer eyJhbGciOiJIUzI1NiIsImVuYyI6IlJTMjU2IiwidHlwIjoiSldUIn0.ey
JqdGkiOiJlZjhlOTgwNS1iYjFiLTRmOTctOTAzYi02YjlhYjgzMGQ2MDQiLCJpc3MiOiJodHRwczovL2
NhbGl0cC5vcmciLCJpYXQiOjE2MzI4OTM0MTYsImFnZW5jeSI6IkFCQyBUcmFuc2l0IENvbXBhbnkiLC
JlbGlnaWJpbGl0eSI6WyJzZW5pb3IiXSwic3ViIjoiQzM0NTY3ODkiLCJuYW1lIjoiU21pdGgifQ.0xp
eyL3GRAQGrGfvreruTra7dbJpjQQ0zLiIqm4H7sE

HTTP Response ¶

HTTP/1.1 200 OK
Date: Wed, 29 Sep 2021 05:30:17 GMT
Content-Type: text/plain; charset=UTF-8
Content-Length: 246

eyJhbGciOiJIUzI1NiIsImVuYyI6IlJTMjU2IiwidHlwIjoiSldUIn0.eyJqdGkiOiJlZjhlOTgwNS1i
YjFiLTRmOTctOTAzYi02YjlhYjgzMGQ2MDQiLCJpc3MiOiJodHRwczovL3ZlcmlmeS5nb3YiLCJpYXQi
OjE2MzI4OTM0MTcsImVsaWdpYmlsaXR5IjpbXX0.LEITzkSGL4Y7uA30pRYxNG7XjDI0lSYtev5X7hNK
Gn4

Response JWT payload ¶

Base64url-decoding the JWT in the response body yields the following payload:

{
  "jti": "ef8e9805-bb1b-4f97-903b-6b9ab830d604",
  "iss": "https://verify.gov",
  "iat": 1632893417,
  "eligibility": []
}

The absence of a value in the eligibility array indicates that the Request subject associated with this JWT (Smith) has not been verified for any eligibility.

Note it is important to return an empty eligibility array rather than an error message or 4xx HTTP code here. This way there is no distinction between “exists in the database” and “does not exist in the database”.

4. Missing request data ¶

The request lacks a sub property, which is required.

Request JWT payload ¶

{
  "jti": "b692fa7c-3dca-4d0d-90ba-e5415af48285",
  "iss": "https://calitp.org",
  "iat": 1632893416,
  "agency": "ABC Transit Company",
  "eligibility": [
    "senior"
  ],
  "name": "Garcia"
}

HTTP Request ¶

The preceding header and payload result in the (signed, Base64url-encoded) JWT used in the following Authorization header:

GET /api/eligibility HTTP/1.1
Host: verify.gov
Authorization: Bearer eyJhbGciOiJIUzI1NiIsImVuYyI6IlJTMjU2IiwidHlwIjoiSldUIn0.ey
JqdGkiOiJiNjkyZmE3Yy0zZGNhLTRkMGQtOTBiYS1lNTQxNWFmNDgyODUiLCJpc3MiOiJodHRwczovL2
NhbGl0cC5vcmciLCJpYXQiOjE2MzI4OTM0MTYsImFnZW5jeSI6IkFCQyBUcmFuc2l0IENvbXBhbnkiLC
JlbGlnaWJpbGl0eSI6WyJzZW5pb3IiXSwibmFtZSI6IkdhcmNpYSJ9.EtnDvEHY1CjldnH-98dIMwdir
pxbNbuCg18R7uR8Gag

HTTP Response ¶

HTTP/1.1 400 Bad Request
Date: Wed, 29 Sep 2021 05:30:17 GMT
Content-Type: text/plain; charset=UTF-8
Content-Length: 258

eyJhbGciOiJIUzI1NiIsImVuYyI6IlJTMjU2IiwidHlwIjoiSldUIn0.eyJqdGkiOiJiNjkyZmE3Yy0z
ZGNhLTRkMGQtOTBiYS1lNTQxNWFmNDgyODUiLCJpc3MiOiJodHRwczovL3ZlcmlmeS5nb3YiLCJpYXQi
OjE2MzI4OTM0MTcsImVycm9yIjp7InN1YiI6Im1pc3NpbmcifX0.1Z53Z2PInyTSQRomcWhcC2Z3c_qL
WoISH7eFv-_JJnE

Response JWT payload ¶

Base64url-decoding the JWT in the response body yields the following payload:

{
  "jti": "b692fa7c-3dca-4d0d-90ba-e5415af48285",
  "iss": "https://verify.gov",
  "iat": 1632893417,
  "error": {
    "sub": "missing"
  }
}

The error message indicates that the Request subject associated with this JWT is missing.

5. Invalid request data ¶

The request’s sub property is not in the correct format.

Request JWT payload ¶

{
  "jti": "d0dbacaf-e691-4ecc-a733-a42a904da607",
  "iss": "https://calitp.org",
  "iat": 1632893416,
  "agency": "ABC Transit Company",
  "eligibility": [
    "senior"
  ],
  "sub": "12345678Z",
  "name": "Garcia"
}

HTTP Request ¶

The preceding header and payload result in the (signed, Base64url-encoded) JWT used in the following Authorization header:

GET /api/eligibility HTTP/1.1
Host: verify.gov
Authorization: Bearer eyJhbGciOiJIUzI1NiIsImVuYyI6IlJTMjU2IiwidHlwIjoiSldUIn0.ey
JqdGkiOiJkMGRiYWNhZi1lNjkxLTRlY2MtYTczMy1hNDJhOTA0ZGE2MDciLCJpc3MiOiJodHRwczovL2
NhbGl0cC5vcmciLCJpYXQiOjE2MzI4OTM0MTYsImFnZW5jeSI6IkFCQyBUcmFuc2l0IENvbXBhbnkiLC
JlbGlnaWJpbGl0eSI6WyJzZW5pb3IiXSwic3ViIjoiMTIzNDU2NzhaIiwibmFtZSI6IkdhcmNpYSJ9.2
w5JhbfIzOSdKWTOrP5CQdhWw9Vo8VunoASe4EVZOoI

HTTP Response ¶

HTTP/1.1 400 Bad Request
Date: Wed, 29 Sep 2021 05:30:17 GMT
Content-Type: text/plain; charset=UTF-8
Content-Length: 258

eyJhbGciOiJIUzI1NiIsImVuYyI6IlJTMjU2IiwidHlwIjoiSldUIn0.eyJqdGkiOiJkMGRiYWNhZi1l
NjkxLTRlY2MtYTczMy1hNDJhOTA0ZGE2MDciLCJpc3MiOiJodHRwczovL3ZlcmlmeS5nb3YiLCJpYXQi
OjE2MzI4OTM0MTcsImVycm9yIjp7InN1YiI6ImludmFsaWQifX0.V_8VA7vWTzwibGE4mfyQ0zAwKhLV
qKDYsl2M55z8rDc

Response JWT payload ¶

Base64url-decoding the JWT in the response body yields the following payload:

{
  "jti": "d0dbacaf-e691-4ecc-a733-a42a904da607",
  "iss": "https://verify.gov",
  "iat": 1632893417,
  "error": {
    "sub": "invalid"
  }
}

The error message indicates that the Request subject associated with this JWT was invalid.