Understanding the access token

The user pool access token contains claims about the authenticated user, a list of the user's groups, and a list of scopes. The purpose of the access token is to authorize API operations. Your user pool accepts access tokens to authorize user self-service operations. For example, you can use the access token to grant your user access to add, change, or delete user attributes.

With OAuth 2.0 scopes in an access token, derived from the custom scopes that you add to your user pool, you can authorize your user to retrieve information from an API. For example, Amazon API Gateway supports authorization with Amazon Cognito access tokens. You can populate a REST API authorizer with information from your user pool, or use Amazon Cognito as a JSON Web Token (JWT) authorizer for an HTTP API. To generate an access token with custom scopes, you must request it through your user pool public endpoints.

Your user's access token is permission to request more information about your user's attributes from the userInfo endpoint. Your user's access token is also permission to read and write user attributes. The level of access to attributes that your access token grants depends on the permissions you assign to your app client, and the scopes that you grant in the token.

The access token is a JSON Web Token (JWT). The header for the access token has the same structure as the ID token. Amazon Cognito signs access tokens with a different key from the key that signs ID tokens. The value of an access key ID (kid) claim won't match the value of the kid claim in an ID token from the same user session. In your app code, verify ID tokens and access tokens independently. Don't trust the claims in an access token until you verify the signature. For more information, see Verifying a JSON Web Token. You can set the access token expiration to any value between 5 minutes and 1 day. You can set this value per app client.

Important

For access and ID tokens, don't specify a minimum less than an hour if you use the hosted UI. Amazon Cognito HostedUI uses cookies that are valid for an hour. If you enter a minimum less than an hour, you won't get a lower expiry time.

Access token header

The header contains two pieces of information: the key ID (kid), and the algorithm (alg).

{
"kid" : "1234example="
"alg" : "RS256",
}

kid

The key ID. Its value indicates the key that was used to secure the JSON Web Signature (JWS) of the token. You can view your user pool signing key IDs at the jwks_uri endpoint.

For more information about the kid parameter, see the Key identifier (kid) header parameter.

alg

The cryptographic algorithm that Amazon Cognito used to secure the access token. User pools use an RS256 cryptographic algorithm, which is an RSA signature with SHA-256.

For more information about the alg parameter, see Algorithm (alg) header parameter.

Access token default payload

This is a sample payload from an access token. For more information, see JWT claims. You can add claims of your own design with a Pre token generation Lambda trigger.

<header>.
{
   "sub":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
   "device_key": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
   "cognito:groups":[
      "testgroup"
   ],
   "iss":"https://cognito-idp.us-west-2.amazonaws.com/us-west-2_example",
   "version":2,
   "client_id":"xxxxxxxxxxxxexample",
   "origin_jti":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
   "event_id":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
   "token_use":"access",
   "scope":"phone openid profile resourceserver.1/appclient2 email",
   "auth_time":1676313851,
   "exp":1676317451,
   "iat":1676313851,
   "jti":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
   "username":"my-test-user"
}
.<token signature>

sub

A unique identifier (UUID), or subject, for the authenticated user. The username might not be unique in your user pool. The sub claim is the best way to identify a given user.

cognito:groups

An array of the names of user pool groups that have your user as a member.

iss

The identity provider that issued the token. The claim has the following format.

https://cognito-idp.<Region>.amazonaws.com/<your user pool ID>

client_id

The user pool app client that authenticated your user. Amazon Cognito renders the same value in the ID token aud claim.

origin_jti

A token-revocation identifier associated with your user's refresh token. Amazon Cognito references the origin_jti claim when it checks if you revoked your user's token with the Revoke endpoint or the RevokeToken API operation. When you revoke a token, Amazon Cognito invalidates all access and ID tokens with the same origin_jti value.

token_use

The intended purpose of the token. In an access token, its value is access.

scope

A list of OAuth 2.0 scopes that define what access the token provides. A token from the Token endpoint can contain any scopes that your app client supports. A token from Amazon Cognito API sign-in only contains the scope aws.cognito.signin.user.admin.

auth_time

The authentication time, in Unix time format, that your user completed authentication.

exp

The expiration time, in Unix time format, that your user's token expires.

iat

The issued-at time, in Unix time format, that Amazon Cognito issued your user's token.

jti

The unique identifier of the JWT.

username

The username of your user in your user pool.

More resources

• How to customize access tokens in Amazon Cognito user pools

Access token signature

The signature of the access token is calculated based on the header and payload of the JWT token. When used outside of an application in your web APIs, you must always verify this signature before accepting the token. For more information, see Verifying a JSON Web Token.