Token types

This page discusses the types of tokens used for authentication to Google APIs, Google Cloud services, and customer-created services hosted on Google Cloud.

If you are accessing Google APIs and services by using a client library, you can set up Application Default Credentials, and the client library handles tokens for you. This is the recommended approach.

What tokens are

For authentication and authorization, a token is a digital object that contains information about the principal making the request and what kind of access they are authorized for. In most authentication flows, the application—or a library used by the application—exchanges a credential for a token, which determines which resources the application is authorized to access.

Types of tokens

Different types of tokens are used in different environments. The following token types are described on this page:

This page does not discuss API keys or Client IDs, which are considered credentials.

Access tokens

Access tokens are opaque tokens that conform to the OAuth 2.0 framework. They contain information about the type of principal used to create the token, as well as authorization information. They are used to authenticate and provide authorization information to Google APIs. Access tokens don't contain the identity of the principal.

If you use Application Default Credentials (ADC) and the Cloud Client Libraries or Google API Client Libraries, you don't need to manage access tokens; the libraries automatically retrieve the credential, exchange it for an access token, and refresh the access token as needed.

Access token contents

Access tokens are opaque tokens, which means that they are in a proprietary format; applications cannot inspect them.

You can get the information from a valid (not expired or revoked) access token by using the Google OAuth 2.0 tokeninfo endpoint.

Replace ACCESS_TOKEN with the valid, unexpired access token.

curl "https://oauth2.googleapis.com/tokeninfo?access_token=ACCESS_TOKEN"

This command returns something similar to the following example:

{
  "azp": "32553540559.apps.googleusercontent.com",
  "aud": "32553540559.apps.googleusercontent.com",
  "sub": "111260650121245072906",
  "scope": "openid https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/cloud-platform https://www.googleapis.com/auth/accounts.reauth",
  "exp": "1650056632",
  "expires_in": "3488",
  "email": "user@example.com",
  "email_verified": "true"
}

The following table lists the most important fields to understand:

Field Description
azp The project, email, or service account ID of the application that requested the token. This value is included only if https://www.googleapis.com/auth/userinfo.email is specified in the list of scopes.
scope The OAuth scopes that have been added to this access token. For Google Cloud services, it is a best practice to use the https://www.googleapis.com/auth/cloud-platform scope, which includes all Google Cloud APIs, together with Identity and Access Management (IAM), which provides fine-grained access control.
expires_in The number of seconds until the token expires. For more information, see Access token lifetime.

Access token lifetime

By default, access tokens are good for 1 hour (3,600 seconds). When the access token has expired, your token management code must get a new one.

If you need an access token with a longer or shorter lifetime, you can use the serviceAccounts.generateAccessToken method to create the token. This method enables you to choose the lifetime of the token, with a maximum lifetime of 12 hours.

If you want to extend the token lifetime beyond the default, you must create an organization policy that enables the iam.allowServiceAccountCredentialLifetimeExtension constraint. For more information, see Create a short-lived access token.

Federated access tokens

Federated access tokens are access tokens returned by the Security Token Service API in exchange for the external credentials generated from federated identities by Workload Identity Federation and Workforce Identity Federation. Federated access tokens are similar to standard access tokens, except for the following differences:

  • Federated access tokens cannot be used for all Google Cloud services. For a list of limitations for federated access tokens, see Identity federation: products and limitations.
  • Federated access tokens assert the external federated identity.

If you need to use an API that does not support federated access tokens, you can use the federated access token to impersonate a service account and generate a standard access token. For more information, see Create a short-lived access token.

For more information about how Google Kubernetes Engine applications authenticate to Google APIs, see About Workload Identity Federation for GKE.

ID tokens

ID tokens are JSON Web Tokens (JWTs) that conform to the OpenID Connect (OIDC) specification. They are composed of a set of key-value pairs called claims.

Unlike access tokens, which are opaque objects that cannot be inspected by the application, ID tokens are meant to be inspected and used by the application. Information from the token, such as who signed the token or the identity for whom the ID token was issued, is available for use by the application.

For more information about Google's implementation of OIDC as used in Google Cloud, see OpenID Connect in the Google Identity documentation. For best practices for working with JWTs, see JSON Web Token Best Current Practices.

ID token contents

You can inspect a valid (not expired or revoked) ID token by using the tokeninfo endpoint.

Replace ID_TOKEN with the valid, unexpired ID token.

curl "https://oauth2.googleapis.com/tokeninfo?id_token=ID_TOKEN"

This command returns something similar to the following example:

{
  "iss": "https://accounts.google.com",
  "azp": "32555350559.apps.googleusercontent.com",
  "aud": "32555350559.apps.googleusercontent.com",
  "sub": "111260650121185072906",
  "hd": "google.com",
  "email": "user@example.com",
  "email_verified": "true",
  "at_hash": "_LLKKivfvfme9eoQ3WcMIg",
  "iat": "1650053185",
  "exp": "1650056785",
  "alg": "RS256",
  "kid": "f1338ca26835863f671403941738a7b49e740fc0",
  "typ": "JWT"
}

The following table describes required or commonly used ID token claims:

Claim Description
iss The issuer, or signer, of the token. For Google-signed ID tokens, this value is https://accounts.google.com.
azp Optional. Who the token was issued to.
aud The audience of the token. The value of this claim must match the application or service that uses the token to authenticate the request. For more information, see ID token aud claim.
sub The subject: the ID that represents the principal making the request.
iat Unix epoch time when the token was issued.
exp Unix epoch time when the token expires.

Other claims might be present, depending on the issuer and the application.

ID token aud claim

The aud claim describes the service name this token was created to invoke. If a service receives an ID token, it must verify its integrity (signature), validity (is it expired) and if the aud claim matches the name it expects. If it does not match, the service should reject the token, because it could be a replay intended for another system.

Generally, when you get an ID token, you use the credentials provided by a service account, rather than user credentials. This is because the aud claim for ID tokens generated using user credentials is statically bound to the application the user used to authenticate. When you use a service account to acquire an ID token, you can specify a different value for the aud claim.

ID token lifetime

ID tokens are valid for up to 1 hour (3,600 seconds). When an ID token expires, you must acquire a new one.

ID token validation

When your service or application uses a Google service such as Cloud Run, Cloud Run functions, or Identity-Aware Proxy, Google validates ID tokens for you; in these cases, the ID tokens must be signed by Google.

If you need to validate ID tokens within your application, you can do so, although this is an advanced workflow. For information, see Validating an ID token.

Self-signed JSON Web Tokens (JWTs)

You can use self-signed JWTs to authenticate to some Google APIs without having to get an access token from the Authorization Server.

Creating self-signed JWTs is recommended if you are creating your own client libraries to access Google APIs, but is an advanced workflow. For more information about self-signed JWTs, see Creating a self-signed JSON Web Token. For best practices for working with JWTs, see JSON Web Token Best Current Practices.

Refresh tokens

By default, access tokens and ID tokens are valid for 1 hour. A refresh token is a special token that is used to obtain additional access tokens or ID tokens. When your application first authenticates, it receives an access token or ID token, as well as a refresh token. Later, if the application needs to access resources again, and the previously provided token has expired, it uses the refresh token to request a new token. Refresh tokens are used only for user authentication, such as for Cloud Identity or Google Workspace.

If your user accounts are managed by an external identity provider (IdP), then that IdP manages the lifetime of long-lived tokens. An exception is local ADC files, which contain refresh tokens used by the authentication libraries to refresh access tokens automatically for client libraries.

Refresh tokens don't have a set lifetime; they can expire, but otherwise they continue to be usable.

For user access in Google Workspace or Cloud Identity premium edition, you can configure the session length to ensure that a user must sign in periodically to retain access to Google Cloud services. If your application is creating and managing its own tokens, it also needs to manage refresh tokens.

For more information, see the following pages in the Google Identity documentation:

Bearer tokens

Bearer tokens are a general class of token that grants access to the party in possession of the token. Access tokens, ID tokens, and self-signed JWTs are all bearer tokens.

Using bearer tokens for authentication relies on the security provided by an encrypted protocol, such as HTTPS; if a bearer token is intercepted, it can be used by a bad actor to gain access.

If bearer tokens don’t provide sufficient security for your use case, consider adding another layer of encryption or using a mutual Transport Layer Security (mTLS) solution such as Chrome Enterprise Premium, which limits access to only authenticated users on a trusted device.

What's next