Tokens and credentials

Amplify Auth interacts with its underlying Amazon Cognito user pool as an OpenID Connect (OIDC) provider. When users successfully authenticate you receive OIDC-compliant JSON web tokens (JWT). These tokens are used to identity your user, and access resources.

Access tokens are used to verify the bearer of the token (i.e. the Cognito user) is authorized to perform an action against a resource. Below is an example payload of an access token vended by Cognito:

  "sub": "54288468-e051-706d-a73f-03892273d7e9",
  "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_yoKn9s4Tq",
  "client_id": "1sg675g08g6g0e9f64grv9n5sk",
  "origin_jti": "0eadb994-a6e0-419e-b309-a7a0d522d72f",
  "event_id": "b180897a-181c-4f73-94bb-a2946e8b4ef1",
  "token_use": "access",
  "scope": "aws.cognito.signin.user.admin",
  "auth_time": 1714241873,
  "exp": 1714245473,
  "iat": 1714241873,
  "jti": "57f10a4d-a1f2-453b-8672-d1cfa8187047",
  "username": "54288468-e051-706d-a73f-03892273d7e9"

ID tokens are intended to be used within your frontend application only. This token contains personally identifiable information (PII) and should not be used to authorize access against a resource. Below is an example of an ID token with the default Amplify Auth configuration of email and password auth.

  "sub": "54288468-e051-706d-a73f-03892273d7e9",
  "email_verified": true,
  "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_yoKn9s4Tq",
  "cognito:username": "54288468-e051-706d-a73f-03892273d7e9",
  "origin_jti": "0eadb994-a6e0-419e-b309-a7a0d522d72f",
  "aud": "1sg675g08g6g0e9f64grv9n5sk",
  "event_id": "b180897a-181c-4f73-94bb-a2946e8b4ef1",
  "token_use": "id",
  "auth_time": 1714241873,
  "exp": 1714245473,
  "iat": 1714241873,
  "jti": "bb69af10-3ce0-47c2-8d8d-5bdc8630ab58",
  "email": "hello@mycompany.com"

When additional user attributes are specified for Amplify Auth, their values will be found in the ID token. For example, if a nickname attribute is requested it will be available on the ID token with the nickname claim:

  "sub": "54288468-e051-706d-a73f-03892273d7e9",
  "email_verified": true,
  "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_yoKn9s4Tq",
  "cognito:username": "54288468-e051-706d-a73f-03892273d7e9",
  "origin_jti": "0eadb994-a6e0-419e-b309-a7a0d522d72f",
  "aud": "1sg675g08g6g0e9f64grv9n5sk",
  "event_id": "b180897a-181c-4f73-94bb-a2946e8b4ef1",
  "token_use": "id",
  "auth_time": 1714241873,
+ "nickname": "hello",
  "exp": 1714245473,
  "iat": 1714241873,
  "jti": "bb69af10-3ce0-47c2-8d8d-5bdc8630ab58",
  "email": "hello@mycompany.com"

Conversely, user pool group claims are found in both the access token and ID token on the cognito:groups claim:

  "sub": "54288468-e051-706d-a73f-03892273d7e9",
  "email_verified": true,
  "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_yoKn9s4Tq",
  "cognito:username": "54288468-e051-706d-a73f-03892273d7e9",
  "cognito:groups": ["ADMINS"],
  "origin_jti": "0eadb994-a6e0-419e-b309-a7a0d522d72f",
  "aud": "1sg675g08g6g0e9f64grv9n5sk",
  "event_id": "b180897a-181c-4f73-94bb-a2946e8b4ef1",
  "token_use": "id",
  "auth_time": 1714241873,
  "nickname": "hello",
  "exp": 1714245473,
  "iat": 1714241873,
  "jti": "bb69af10-3ce0-47c2-8d8d-5bdc8630ab58",
  "email": "hello@mycompany.com"

Visit the AWS documentation for using tokens with Cognito user pools to learn more about tokens, how they're used with Cognito, and their intended usage.

Understand token management options

Token keys are automatically rotated for you for added security but you can update how they are stored, customize the refresh rate and expiration times, and revoke tokens on sign-out.

Update your token-saving mechanism

You can update the storage mechanism to choose where and how tokens are persisted in your application. The default option is localStorage. Additionally, you can import the sessionStorage, sharedInMemoryStorage or CookieStorage options as well.

If you want to customize your own mechanism, you can import the KeyValueStorageInterface interface and implement it in your own class.

Browser Local Storage

In Amplify the localStorage is the default storage mechanism. It saves the tokens in the browser's localStorage. This local storage will persist across browser sessions and tabs. You can explicitly set to this storage by calling:

import { cognitoUserPoolsTokenProvider } from 'aws-amplify/auth/cognito';
import { defaultStorage } from 'aws-amplify/utils';
cognitoUserPoolsTokenProvider.setKeyValueStorage(defaultStorage);

CookieStorage saves the tokens in the browser's Cookies. The cookies will persist across browser sessions and tabs. You can explicitly set to this storage by calling:

import { cognitoUserPoolsTokenProvider } from 'aws-amplify/auth/cognito';
import { CookieStorage } from 'aws-amplify/utils';
cognitoUserPoolsTokenProvider.setKeyValueStorage(new CookieStorage());

Browser Session Storage

sessionStorage saves the tokens in the browser's sessionStorage and these tokens will clear when a tab is closed. The benefit to this storage mechanism is that the session only lasts as long as the browser is open and you can sign out users when they close the tab. You can update to this storage by calling:

import { cognitoUserPoolsTokenProvider } from 'aws-amplify/auth/cognito';
import { sessionStorage } from 'aws-amplify/utils';
cognitoUserPoolsTokenProvider.setKeyValueStorage(sessionStorage);

Custom Storage

You can implement your own custom storage mechanism by creating a class that implements the storage interface. Here is an example that uses memory storage:

import { cognitoUserPoolsTokenProvider } from 'aws-amplify/auth/cognito';
import { KeyValueStorageInterface } from 'aws-amplify/utils';
class MyCustomStorage implements KeyValueStorageInterface {
  storageObject: Record<string, string> = {};
  async setItem(key: string, value: string): Promise<void> {
    this.storageObject[key] = value;
  async getItem(key: string): Promise<string | null> {
    return this.storageObject[key];
  async removeItem(key: string): Promise<void> {
    delete this.storageObject[key];
  async clear(): Promise<void> {
    this.storageObject = {};
cognitoUserPoolsTokenProvider.setKeyValueStorage(new MyCustomStorage());

When you get the current user session, the tokens will be saved in your custom location.

Token Revocation

Token revocation is enabled automatically in Amplify Auth. To revoke tokens you can set up global sign-out with signOut({ global: true }) to globally sign out your user from all of their devices.

Next steps

Guest access