OpenPass authentication tokens

The ID token is part of the response to the POST /v1/api/token API call. It is a JSON Web Token (JWT) that includes the claim associated with the user. A claim is a piece of information about the user that is returned after user authentication, such as their user email address.

If you're using an SDK, the SDK manages the token information for you. If not, you can write code to decode the token and use the values, and verify the signature.

You could decode the token at web token debugger site such as https://jwt.io/ by doing the following:

  1. Copy and paste the ID token in the Encoded field.
  2. Copy and paste the ID token signature in the Verify Signature field.

The following example is a snippet from a valid response to a call to the POST /v1/api/token endpoint, with the ID token. The ellipsis indicates that additional properties in the response example are not shown.

{
  "id_token":"eyJraWQiOiJUc1F0cG5ZZmNmWm41ZVBLRWFnaDNjU1lGcWxnTG91eEVPbU5YTVFSUWVVIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiI5ZTJkNzRlMi0wODQxLTQ4YzAtYmIzYy0xOTNjMzg2MjQ3ZTAiLCJhdWQiOiIxMjM0NTY3ODkwIiwiaXNzIjoiaHR0cHM6Ly9teW9wZW5wYXNzLmNvbSIsImV4cCI6MTY3MzAzMDM3MywiaWF0IjoxNjcwNDM4MzczLCJlbWFpbCI6InRlc3RAZXhhbXBsZS5jb20ifQ.d_OkLveN8KhRcz3DioQsFTPnTg0rb1FUBCr-pMOW037vScCXcwk2e6WwxA1DFkppxPLvW1It-ZmDEeQ-P7YVcrfAQqzsOhf8gXJTQNAfQOnNmRjVn8V98S-OsWvHIRDierjjnJwypNqU80fllvX95UMDaQkK_IpYxx2b6fBxj48rLEl9MCdlMO1Igg088gT62SfeV_gqSbEnbuL5GbOQ-zKVKN_F0V06Y0ndUeCiWNATkmOFomMmzlCL_99VrGIPwzGJ1QGg3mRmkZizvH38lvHJ8fwVPOQqodLvP50ixBwjqMthP0mqMy97g2rKo0KGBIaH4ngnGOtSGNUhJARLBg",
...
}

ID token header and payload

At https://jwt.io/, the token in this sample response gives the following results:


The three dot-separated sections of the JWT token are as follows:

  1. Header
  2. Payload
  3. Signature

JWT header

The JWT header includes metadata about the token in the form of the header parameters shown in the following table.

For details, see JOSE Header in the JWT specification and Registered Header Parameter Names in the JSON Web Signature (JWS) specification.

Header Parameter Meaning Sample Value
kid A unique ID indicating the key that was used for the signature. For details, see "kid" (Key ID) Header Parameter in the JSON Web Signature specification.
You can use the kid value to find the key at the GET /.well-known/jwks endpoint and then use the key to decode the JWT token signature.		 VSgwvbXeulFW0LiSo_dLjJrCkvAVN06euw7Ie0FC8p0
typ Indicates the type of token. For OpenPass it is always JWT. JWT
alg Indicates the encryption algorithm used for signing the token. For OpenPass, it is always RS256. For details, see "alg" (Algorithm) Header Parameter in the JSON Web Signature specification. RS256

JWT payload

The second part of the token, the JWT payload, includes the values and claims shown in the following table.

Payload Claim Meaning Sample Value
jti The unique identifier, indicating a UUID for the JWT. bc116f3b-7818-41af-badf-9eab1a0d3240
sub The subject value, indicating a UUID (universally unique ID) for the user. 34716067-c9cd-47d7-a6a7-d646fe9e2ecf
email The user's email address. test@example.com
given_name The given or first name of the end user. Here are key points:
  • Max 50 characters.
  • In some cultures, individuals may have multiple given names — enter all given names as a single field with parts separated by spaces.
 Gabriel Jose
family_name The surname or last name of the end user. Here are key points:
  • Max 100 characters.
  • In some cultures, individuals may have multiple family names or no family name — enter all family names as a single field with parts separated by spaces, hyphens, or apostrophes.
 Garcia Marquez, Smith-Johnson, D'Angelo
name The full name of the end user. Here are key points:
  • Can be used instead of the given_name and family_name parameters.
  • Max 150 characters.
  • In some cultures, names don't fit a first-last format — enter the whole name as a single field with parts separated by spaces, hyphens, or apostrophes.
 Gabriel Jose Garcia Marquez
aud The audience value, indicating the entity that will consume the token. The aud value is the Client ID for the OpenPass account. 29352915982374239857
iss The issuer value, indicating the entity that issued the token. https://auth.myopenpass.com
iat The issued at value, indicating the timestamp for when the token was issued. Must be a number representing a UTC time value. 1661270025
exp The expiration value, indicating the expiration timestamp for the token. 1663862025

JWT signature

The last part of the token is the signature. The token is signed with the OpenPass private key according to the JSON Web Token (JWT) specification. The organization must verify the signature using the OpenPass public key. Signature verification confirms that the token is genuine—it proves the token was signed by the OpenPass server using the OpenPass private key.

To identify the correct OpenPass public key, follow these steps:

  1. Find the key at the GET /.well-known/jwks endpoint using the kid value in the JWT header.
  2. Decode the signature by applying the public key in a web token debugger site. Use all values in the applicable key from the JSON Web Key Set (JWKS) endpoint.

ID token signature: Example

The following shows all the values in the JWS key used for the example in this section. The kid value is the second value in the key.

{
  "kty": "RSA",
  "kid": "TsQtpnYfcfZn5ePKEagh3cSYFqlgLouxEOmNXMQRQeU",
  "n": "x7PX7QkS0DuOELNq6UrI-oAhNSibSDIP27twYAo9jnW3EI1Cv76Dgiv4jJMfNjAv4NUgJ2NidZeBhq2YXwZx9W4vdFfK2NwMWwZ5EWx_MRTH972fndQaTUh5Gw1beA_dRV4NMik_MPE3QTuwXcqgdnIb4efv955OP_KbMOI63RIhhgh4GddF-22Uy0UsQcfDPsWUpGS9mafUTG3HAiwaTg7A9HWrAAN2QJmXeIgKR2zd3KB7S1pB63F7exh1qMqEmtwV1D5u1ee_zacJGs1P7X1eggkQIC4vdoaq_j0rnvDWtcvbeCwHj2l6ixJmsBc6BwPjZWoxNas7lwbhDlbnDQ",
  "e": "AQAB"
}

For more information on the values in a key, see Parameters for RSA Keys in the JSON Web Algorithms (JWA) specification.

At https://jwt.io/, when you provide the key successfully, the page displays "Signature Verified" at the bottom-left corner of the webpage. When the signature is verified, it confirms that the token was sent by the specified issuer, the OpenPass authentication server.