Access tokens are credential strings that represent authorization to access a protected resource. Client applications obtain access tokens by making OAuth 2 or OpenID Connect requests to an authorization server; resource servers require clients to authenticate using access tokens.

Access tokens are obtained from the token endpoint (when using the client credentials grant type) or from the authorization endpoint (when using the implicit grant type). Access tokens are typically granted on behalf of a specific authenticated user. (Tokens granted directly to applications are called application tokens.)

Clients present access tokens when making requests to a resource server (for example, the PingOne API endpoints) using bearer token authentication as described by RFC 6750. Here is a sample request using an access token:

curl -X GET "https://api.pingone.com/v1/environments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6InRlc3QifQ.eyJzY29wZSI6IiIsImNsaWVudF9pZCI6ImlkZW50aXR5LWRpcmVjdG9yeS1zeW50aGV0aWMtdGVzdGluZyIsImlzcyI6ImF1dGgtc3RhZ2luZy5waW5nb25lLmNvbSIsImF1ZCI6ImFwaS1zdGFnaW5nLnBpbmdvbmUuY29tIiwiYWNjIjoiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwIiwiZW52aXJvbm1lbnRfaWQiOiIiLCJvcmciOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJvcmdhbml6YXRpb25faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJlbnYiOiIiLCJleHAiOjE1MzAxMTc1Nzl9.OTGQethw-flgnf0oslpQOmW9YdExf6ZpsqpmRtBTeD5gpKGFmaSeHguFMVpR94GSjb27OEPzCY8qpU_OkoaQGH9FiysdgvFFVNVzHOb80e0MgP47ean1Rtk3lHmIWHg1ihp3Kt7vq9fO0OwekmfshejyaLYLX2g4seWFZKbs7ICIaSufYuGTsLLQFixiK7b0tM-lcjZUmLglPlzdGEYQgg13ZWho02rFVjwRrfOVkQRCLuhkk2Pz2eeblQgWBlzMi_zbHnRhqRnrHyX2PwoPZ9qHh3aqz6yNgGinUwSrE3J1slnx8uPeP88obYcX4QXTXOCf7su2rinbexOsNu4Puw"

Grant types

OAuth 2 and OpenID Connect define the authorization grant types by which a client application obtains an authorization grant in the form of an access token. PingOne supports the following grant types:

Authorization code

This grant type is used by web applications. The authorization request generates an authorization code that is exchanged for an access token. For more information, see Authorization request with a code grant.

Implicit

This grant type is intended for use by native applications or client-side web applications with no server-side component. The implicit grant type is for applications that cannot guarantee the confidentiality of the client secret.

In this flow, the client makes a request to the server’s authorization endpoint. If the request contains the id_token response type and the openid scope, then it is considered an authentication (OpenID Connect) request, and an ID token is issued. For more information, see Native and single-page applications.

Client credentials

This grant type is made directly to the token endpoint and is used to request an access token for either:

The client uses HTTP basic authentication with its client ID and client secret to authenticate itself to the token endpoint and must specify a Content-Type of application/x-www-form-urlencoded. For more information, see Obtain an access token.

Refresh token

This grant type is used by applications to exchange the refresh token for a new access token. It gives applications the ability to acquire a valid access token without additional interaction. For more information, see Obtain an access token.

Response types

The authorization request must specify a response_type attribute, which determines whether an access token, an authorization code, or an ID token is returned by the authorization server. The following is the list of the OAuth 2.0 response types supported by the PingOne authorization server:

Token claims

All tokens in PingOne are JSON Web Tokens (JWTs) signed using the RS256 signing algorithm. The following section lists the supported claims for each token type.

Access token claims

For access tokens, the JWT header must contain the ID of the signing key as the kid claim.

Claim Description
sub A string that specifies the identifier for the authenticated user. This claim is not present for client_credentials tokens.
client_id A string that specifies the application that requested this token.
aud A string that lists the names of resources that this token is intended for. The resource of an application’s resource access grant is included if one or more scopes from the grant is requested and granted.
scope A string that specifies the space-separated list of scope names associated with this token in the format described in Section 3.3 of OAuth 2.0 RFC6749.
iss A string that specifies the per-environment issue URI: For example, https://auth.pingone.com/<environmentId>/as.
iat An integer that specifies the timestamp, measured in the number of seconds since January 1, 1970, UTC, indicating when this token was originally issued, as defined in JWT RFC7519.
exp An integer that specifies the timestamp, measured in the number of seconds since January 1, 1970, UTC, indicating when this token will expire, as defined in JWT RFC7519.
env A string that specifies the environment ID of the authenticated user or application. This claim is not present when the resource’s audience property does not include the PingOne platform API resource.
org A string that specifies the organization ID of the authenticated user or application. This claim is not present when resource’s audience property does not include the PingOne platform API resource.

ID Token claims

ID tokens are signed with the same key as the access token. The JWT header must contain the ID of the signing key as the kid claim.

Claim Description
sub A string that specifies the identifier for the authenticated user.
aud A string that lists the names of resources that this token is intended for. The resource of an application’s resource access grant is included if one or more scopes from the grant is requested and granted.
iss A string that specifies the per-environment issuer URI: https://auth.pingone.com/<environmentId>/as or https://<customDomain>/as.
iat An integer that specifies the timestamp, measured in the number of seconds since January 1, 1970, UTC, indicating when this token was originally issued, as defined in JWT RFC7519.
exp An integer that specifies the timestamp, measured in the number of seconds since January 1, 1970, UTC, indicating when this token will expire, as defined in JWT RFC7519.
auth_time A string that specifies the time when the user authentication occurred. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the current date and time.
nonce A string that specifies the value used to associate a client session with an id_token, and to mitigate replay attacks. The value is passed through unmodified from the authentication request to the ID token.
at_hash A case-sensitive string that specifies the access token hash value, which is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the access token value. For more information, see OpenID Connect Core 1.0.
c_hash A case-sensitive string that specifies the code hash value, which is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the code value. For more information, see OpenID Connect Core 1.0.
acr A string that specifies the name of the sign-on policy that was completed when the original authentication was performed. This claim is present only if an ID token was minted.
amr A string array that specifies the methods associated with the authenticators used when the original authentication was performed. This claim is present only if an ID token was minted.

Refresh tokens

Refresh tokens are JWTs signed with the same key as the access token. They are not intended to be read by the client. For more information about refresh token usage, see Obtain an access token.

Access token customization

PingOne lets you customize the content of access tokens by adding custom resource attributes and their values to the token. You can use the access token customization APIs to convey additional information about the user to applications. For more information, see Resource attributes.

ID token customization

You can also customize the content of OIDC ID tokens by adding custom user claims to the token. For more information, see Attribute mappings.

Token analysis

The PingOne platform supports endpoints to returns the active state of an OAuth 2.0 token and all of the claims in the token. The request takes a token parameter, which is the token string. For more information, see Token introspection.