) or https:// means you've safely connected to the .gov website. Share sensitive information only on official, secure websites.
Developers
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
client_assertion
required for private_key_jwtA 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.
code_verifier
required for PKCE
The original value (before the SHA256) generated for the authorization request for PKCE that corresponds to the
code_challenge.
grant_type
authorization_code
POST https://idp.int.identitysandbox.gov/api/openid_connect/token
code=${CODE}&
code_verifier=${CODE_VERIFIER}&
grant_type=authorization_code
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.
{
"access_token": "hhJES3wcgjI55jzjBvZpNQ",
"token_type": "Bearer",
"expires_in": 3600,
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJiMmQyZDExNS0xZDdlLTQ1NzktYjlkNi1mOGU4NGY0ZjU2Y2EiLCJpc3MiOiJodHRwczovL2lkcC5pbnQubG9naW4uZ292IiwiYWNyIjoiaHR0cDovL2lkbWFuYWdlbWVudC5nb3YvbnMvYXNzdXJhbmNlL2xvYS8xIiwibm9uY2UiOiJhYWQwYWE"
}
{
"sub": "b2d2d115-1d7e-4579-b9d6-f8e84f4f56ca",
"iss": "https://idp.int.identitysandbox.gov",
"acr": "http://idmanagement.gov/ns/assurance/ial/1",
"nonce": "aad0aa969c156b2dfa685f885fac7083",
"aud": "urn:gov:gsa:openidconnect:development",
"jti": "jC7NnU8dNNV5lisQBm1jtA",
"at_hash": "tlNbiqr1Lr2YcNRGjzwlIg",
"c_hash": "hXjq7kOrtQK_za_6tONxcw",
"exp": 1489694196,
"iat": 1489694198,
"nbf": 1489694198
}
