Skip to main content
U.S. flag

An official website of the United States government

Dot gov

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Https

Secure .gov websites use HTTPS
A lock ( Https ) or https:// means you've safely connected to the .gov website. Share sensitive information only on official, secure websites.

OpenID Connect

OpenID Connect (OIDC) is a simple identity layer built on top of the OAuth 2.0 protocol. Login.gov supports version 1.0 of the specification and conforms to the iGov Profile.

Token

Clients use the token endpoint to exchange the authorization code for an access_token. This token is needed to access the user info endpoint. To request a token, send a HTTP POST request to the /api/openid_connect/token endpoint.

View an example for private_key_jwt or PKCE in the side panel.

Request Parameters

  • JWT
  • PKCE

client_assertion

required for private_key_jwt

A JWT signed with the client’s private key (minimum length of 2048 bits) associated with the public key uploaded to your application configuration within the Dashboard. The JWT should use the RS256 algorithm and containing the following claims:

  • iss (string) — The issuer, which must be the client_id.
  • sub (string) — The subject, which must also be the client_id.
  • aud (string) — The audience, which should be (or, in the case of multiple audience values, include) the URL of the token endpoint, for example: https://idp.int.identitysandbox.gov/api/openid_connect/token
  • jti (string) — The JWT ID, a unique identifier for the token which can be used to prevent reuse of the token. Should be an unguessable, random string generated by the client.
  • exp (number) — The expiration time for this token. Should be an integer timestamp (number of seconds since the Unix Epoch) and be a short period of time in the future (such as 5 minutes from now).

client_assertion_type

required for private_key_jwt
When using private_key_jwt, must be urn:ietf:params:oauth:client-assertion-type:jwt-bearer

code

The authorization code returned by the authorization response.

grant_type

authorization_code
JWT Request
POST https://idp.int.identitysandbox.gov/api/openid_connect/token

client_assertion=${CLIENT_ASSERTION}&
client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&
code=${CODE}&
grant_type=authorization_code

Token response

The token response will be a JSON object containing the following:

access_token (string)

An unique token used to access the user info endpoint.

token_type (string)

The type of access token, which will always be Bearer.

expires_in (number)

The number of seconds the access token will expire.

id_token (string)

A signed JWT that contains basic attributes about the user and it is signed using the RS256 algorithm. The public key used to verify this JWT is available from the certificates endpoint.

The id_token contains the following claims:

iss (string)

The issuer of the response, which will be the URL of the Login.gov IdP, for example: https://idp.int.identitysandbox.gov.

sub (string)

The subject identifier, the UUID of the Login.gov user (see user attributes).

aud (string)

The audience, which will be the client_id.

acr (string)

The Authentication Context Class Reference value of the returned claims, from the original authorization request.

at_hash (string)

The access token hash, a URL-safe base-64 encoding of the left 128 bits of the SHA256 of the access_token value. Provided so the client can verify the access_token value.

c_hash (string)

The code hash, a URL-safe base-64 encoding of the left 128 bits of the SHA256 of the authorization code value. Provided so the client can verify the code value.

exp (number)

The expiration time for this token, an integer timestamp representing the number of seconds since the Unix Epoch.

iat (number)

Time at which the JWT was issued, an integer timestamp representing the number of seconds since the Unix Epoch.

jti (number)

The JWT ID, a unique identifier for the token which can be used to prevent reuse of the token. Should be an unguessable, random string generated by the client.

nbf (number)

The “not before” value, an integer timestamp of when the token will start to be valid (number of seconds since the Unix Epoch).

nonce (string)

The nonce value provided by the client in the authorization request. A unique value, at least 22 characters in length, used to verify the integrity of the id_token and mitigate replay attacks. This value should include per-session state and be unguessable by attackers. Read more about nonce implementation in the spec.
Next step: User info
{
  "access_token": "hhJES3wcgjI55jzjBvZpNQ",
  "token_type": "Bearer",
  "expires_in": 3600,
  "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJiMmQyZDExNS0xZDdlLTQ1NzktYjlkNi1mOGU4NGY0ZjU2Y2EiLCJpc3MiOiJodHRwczovL2lkcC5pbnQubG9naW4uZ292IiwiYWNyIjoiaHR0cDovL2lkbWFuYWdlbWVudC5nb3YvbnMvYXNzdXJhbmNlL2xvYS8xIiwibm9uY2UiOiJhYWQwYWE"
}
Next step: User info
Edit this page
Return to top