Identity as a Service:GenerateToken

The following methods are supported: Authorization Code, Device Flow, Refresh Token, Client Credentials, and Password.

1. Authorization Code

Scenario: This is the standard OAuth 2.0 authorization code flow, which is suitable for web applications with frontend interaction. Example call:

POST /v2/{instanceId}/{applicationId}/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code={authorization_code}
&redirect_uri={redirect_uri}
&client_id={client_id}
&client_secret={client_secret}

Parameters:

● code: The authorization code obtained from the authorization endpoint.

● redirect_uri: Must be the same as the redirect_uri that was used to obtain the authorization code.

1.1 Authorization Code for public clients

Scenario: This scenario is suitable for applications that cannot securely store a secret, such as single-page applications (SPAs) or native applications. In this flow, a client_secret is not required, but you must use the Proof Key for Code Exchange (PKCE) mechanism. Example call:

POST /v2/{instanceId}/{applicationId}/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code={authorization_code}
&redirect_uri={redirect_uri}
&client_id={client_id}
&code_verifier={code_verifier}

Parameters:

● code_verifier: The code verifier for the PKCE mechanism. The client generates it when initiating an authorization request and uses it to derive the `code_challenge`. When exchanging for a token, you must submit this value. It must be identical to the value used to generate the `code_challenge`.

Java example for generating a code_verifier and code_challenge:

String codeVerifier = Base64.getUrlEncoder().withoutPadding().encodeToString(new SecureRandom().generateSeed(43));
String codeChallenge = Base64.getUrlEncoder().withoutPadding().encodeToString(java.security.MessageDigest.getInstance("SHA-256").digest(codeVerifier.getBytes()));

2. Device Flow

Scenario: This scenario is suitable for input-constrained devices, such as TVs and IoT devices. Example call:

POST /v2/{instanceId}/{applicationId}/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:device_code
&device_code={device_code}
&client_id={client_id}
&client_secret={client_secret}

To obtain the device code, first call /oauth2/device/code to retrieve the device_code and user_code.

2.1 Device Flow for public clients

Scenario: This scenario is used when interactive logon is not convenient and the client is a public client. Example call:

POST /v2/{instanceId}/{applicationId}/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:device_code
&device_code={device_code}
&client_id={client_id}

3. Refresh Token

Scenario: This scenario uses a refresh_token to obtain a new access_token. Example call:

POST /v2/{instanceId}/{applicationId}/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token={refresh_token}
&client_id={client_id}
&client_secret={client_secret}

4. Client Credentials

Scenario: This scenario is for server-to-server authentication without user involvement. Example call:

POST /v2/{instanceId}/{applicationId}/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={client_id}
&client_secret={client_secret}
&scope={scope}

5. Password

Scenario: This scenario uses traditional username and password authentication. Use this method with caution. Example call:

POST /v2/{instanceId}/{applicationId}/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=password
&username={username}
&password={password}
&client_id={client_id}
&scope={scope}