Access token overview

Last updated on Aug 25, 2023

What is an access token

An access token, also called an API token, is an object or file that enables access to an application or resource.

The token is digitally signed and contains information about what resources can be accessed and for how long.

Why do we have access tokens

Access tokens allow you to avoid using secret credentials, a.k.a. passwords, to authenticate API calls.

Rather than using “Basic” authentication and including credentials in the Authorization header of an HTTP request, you can include a signed token instead. This is known as "Bearer” authentication.

Are there other token types

The OAuth and OIDC set of specifications define access_tokens, id_tokens, and refresh tokens.

Is it API token or access token?

The terms 'API token' and 'access token' refer to the same type of token. These are distinct from id tokens and refresh tokens.

Self-contained vs referential tokens

Access tokens may contain all the information needed to validate them, or they may require relying parties to call an endpoint for validation. The former are called self-contained tokens and are encoded in JWS format. The latter are called referential tokens and are encoded in JWE.

Access token contents

The information contained in (or referenced by) an access token varies, but some elements are common:

• Issuer ID: The issuer of the token is the authority responsible for the token. The issuer's ID is commonly the URL (such as a Beyond Identity app URL) that received and responded to the token request

• Audience: The identifier of the app or API that will consume the token

• Subject: An identifier of either the user or the app the token represents / was issued to

• Scope: One or more identifiers of specific access levels the token will allow. Find out more about scopes here.

How to get a token

You can obtain tokens via the Beyond Identity console or programmatically via the Beyond Identity API.

App properties that impact token requests and token validation

In order to request a token, you need to have an app configured in your Beyond Identity tenant.

This can be an application you configure yourself, or you can request a token for the built in Beyond Identity Management API app.

The application's External Protocol settings determine how tokens should be requested, what tokens issued for the app look like, and how they should be validated.

Client Configuration

Setting	Impact
Protocol	Determines which protocol flow the app must use to request tokens: OAuth2: With the OAuth2 protocol, you can use either the client credentials grant type or the authorization code grant type. OIDC: With the OIDC protocol, you must use the authorization code grant type. With OIDC, you can obtain an id_token as well as an access_token. For help determining which to select, see API Token Request Scenarios
Client Type	Confidential: Confidential clients are applications that are able to keep their registered client credentials (such as a client secret) safe. Think of an application with a backend. The client credentials can then be used to authenticate calls to the token APIs. Public: Public clients, such as applications running in a browser or on a mobile device, are unable to protect registered client secrets and are not issued client credentials.
PKCE	If the app's PKCE setting is S256, the app will need to create and send the PKCE parameters (code_challenge, code_challenge_method, and code_verifier) in token requests as described in this Create an access token example If PKCE is set to Disabled, you do not need to send the PKCE parameters (code_challenge, code_challenge_method, and code_verifier) in your token requests. However, authorization code grant with PKCE is the recommended flow for token requests and is required for public clients.
Redirect URIs	A list of valid URIs to redirect the resource owner's user-agent to after completing its interaction with the authorization server. See Section 3.1.2 for more information.
Token Endpoint Auth Method	Client Secret Basic: The client uses HTTP Basic as defined in OAuth 2.0, Section 2.3.1. The client ID and client secret are sent in the Basic Authorization header. Client Secret Post: The client uses the HTTP POST parameters as defined in OAuth 2.0, Section 2.3.1. The client ID and client secret are sent in the body of the POST request.
Grant Type	Authorization Code: The authorization code grant type defined in OAuth 2.0, Section 4.1. Namely, the client may authorize to the token endpoint with a grant code which it obtains via the authorize endpoint. Client Credentials: The client credentials grant type defined in OAuth 2.0, Section 4.4. Namely, the client may authorize to the token endpoint with a client credentials tuple of client_id and client_secret. If you select Client Credentials, the application cannot have an associated authenticator configuration.
Resource Server	If the app is linked to a resource server, the resource server determines the scopes the app can be allowed to issue.
Token Format	The two options for token format are Self-Contained and Referential. The difference between these two options impacts how the tokens will be validated. Self-Contained tokens can be validated offline because they contain all of the validation information. Referential tokens require a call to the introspection endpoint for validation.

Token Configuration

Setting	Impact
Allowed Scopes	If the app is configured with a Resource Server, then this setting specifies the scopes allowed to be included in tokens for this application. The allowed scopes can match or be a subset of the Resource Server scopes
Expires	Token lifetime in seconds
Subject	Property of a principal which is used to fill the subject of a token issued for this application.
Token Signing Algorithm	Signing algorithm to use for an application token. The only allowable value at present is RS256.

Refresh Token Configuration

Setting	Impact
Enable Refresh Tokens	When enabled, the token response JSON object will contain an additional field called refresh_token, similar to RFC6749#4.1.4.