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.

Amplify Auth persists authentication-related information to make it available to other Amplify categories and to your application.

Amplify Flutter securely manages credentials and user identity information. You do not need to store, refresh, or delete credentials yourself. Amplify Flutter stores auth data on the device using platform capabilities such as Keychain Services on iOS and macOS and EncryptedSharedPreferences on Android.

Amplify will refresh the access token and ID token as long as the refresh token is valid. Once the refresh token expires, the user will need to reauthenticate to obtain a new one.

Some platform specific option can be customized with the out of the box options. In the example below, credentials will be stored in-memory on Web instead of the default behavior of using browser storage.

await Amplify.addPlugin(
  AmplifyAuthCognito(
    secureStorageFactory: AmplifySecureStorage.factoryFrom(
      webOptions: WebSecureStorageOptions(
        persistenceOption: WebPersistenceOption.inMemory,

If you would like further customization, you can provide your own factory for creating SecureStorageInterface instances to AmplifyAuthCognito. The example below shows the use of a custom implementation that stores data in-memory on all platforms.

await Amplify.addPlugin(
  AmplifyAuthCognito(secureStorageFactory: InMemoryStorage.new),

class InMemoryStorage implements SecureStorageInterface {
  InMemoryStorage(this.scope);
  /// The scope of the item being stored.
  /// This can be used as a namespace for stored items.
  final AmplifySecureStorageScope scope;
  static final Map<String, String> _data = {};
  @override
  void write({required String key, required String value}) {
    _data['${scope.name}.$key'] = value;
  @override
  String? read({required String key}) {
    return _data['${scope.name}.$key'];
  @override
  void delete({required String key}) {
    _data.remove('${scope.name}.$key');

Token Revocation

Token revocation is enabled automatically in Amplify Auth. To revoke tokens you can invoke await Amplify.Auth.signOut(options: const signOutOptions(globalSignOut: true)) to globally sign out your user from all of their devices.

Next steps

Guest access