/token: Token

URL:
https://[root]/oauth2/token
Methods:
GET

Example usage

Use dark colors for code blocksCopy
1
https://www.arcgis.com/sharing/rest/oauth2/token

Description

The first step of an authorization grant is the authorization, and the access token step of that flow is described below. In addition to issuing user access tokens as part of the authorization grant, this end point can also be used to refresh access tokens and issue application tokens. The overall OAuth2 authentication flow is described in Authentication.

The type of token issued is based on the grant_type parameter as follows:

  • authorization_code
  • client_credentials
  • exchange_refresh_token
  • refresh_token

The required request parameters vary based on the grant_type as specified in the following table:

Grant typeRequired parameters

authorization_code

  • client_id
  • code
  • redirect_uri

client_credentials

  • client_id
  • client_secret

exchange_refresh_token

  • client_id
  • redirect_uri
  • refresh_token

refresh_token

  • client_id
  • refresh_token

Request parameters

ParameterDetails

client_id

(Required)

The ID of the registered application. This is also referred to as APPID.

Example:

Use dark colors for code blocksCopy
1
client_id=GGjeDjEY6kKEiDmX

grant_type

(Required)

The type of grant requested.

The type of token issued is based on the grant_type values as follows:

  • authorization_code— A user access_token and refresh_token are issued based on the authorization code obtained in the authorization step. Access tokens are typically short lived (approximately 30 minutes). You can get a new access_token for apps using the refresh_token obtained with this grant. Starting with the March 2022 ArcGIS Online release, support for Proof Key for Code Exchange (PKCE) has been added. PKCE is an extension to the authorization grant flow and is recommended for all apps including web apps.
  • client_credentials— An app access_token is issued for the client_id specified in the request.
  • exchange_refresh_token— A new refresh_token is issued by exchanging the previous refresh_token.
  • refresh_token— A new access_token is issued using the refresh_token obtained above.

Example:

Use dark colors for code blocksCopy
1
grant_type=authorization_code

client_secret

(Required when grant_type=client_credentials)

The secret of the registered application. This is also referred to as APPSECRET.

Example:

Use dark colors for code blocksCopy
1
client_secret=57e2f75cd56346bf9d5654c3338a1250

code

(Required when grant_type=authorization_code)

The authorization code obtained as a result of the authorization step.

Example:

Use dark colors for code blocksCopy
1
code=KIV31WkDhY6XIWXmWAc6U

redirect_uri

(Required when grant_type=authorization_code or grant_type=exchange_refresh_token)

The URI specified during the authorization step. The URIs must match; otherwise, authorization will be rejected.

Example:

Use dark colors for code blocksCopy
1
redirect_uri=https://app.example.com/cb

refresh_token

(Required when grant_type=token or grant_type=exchange_refresh_token)

The request_token obtained in response to grant_type=authorization_code.

Example:

Use dark colors for code blocksCopy
1
refresh_token=GysTpIui-oxWTTIs

code_verifier

The code verifier for the PKCE request that was generated before the authorization request.

If the verifier matches the expected value, the server issues an access token. Otherwise, the server responds with following error:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
{
  "error": {
    "code": 400,
    "error": "invalid_request",
    "error_description": "Invalid PKCE code_challenge_verifier",
    "message": "Invalid PKCE code_challenge_verifier",
    "details": []
  }
}

JSON Response example

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
{
  "access_token": "2YotnFZFEjr1zCsicMWpAA",
  "expires_in": 1800, // expiration in seconds from now
  "username": "jsmith", //signed-in username
  "ssl" :true, //Returned true for ArcGIS Online
  "refresh_token": "GysTpIui-oxWTTIs" // ONLY returned when grant_type=authorization_code or grant_type=exchange_refresh_token
  "refresh_token_expires_in": 604799 // expiration in seconds from now
}

Examples

This end point is used for all examples:

Use dark colors for code blocksCopy
1
https://www.arcgis.com/sharing/rest/oauth2/token

grant_type=authorization_code

Assume these parameters:

Use dark colors for code blocksCopy
1
2
3
4
client_id=GGjeDjEY6kKEiDmX&
grant_type=authorization_code&
redirect_uri=https://app.example.com/cb&
code=KIV31WkDhY6XIWXmWAc6U

PKCE flow

Assume these parameters:

Use dark colors for code blocksCopy
1
2
3
4
5
client_id=GGjeDjEY6kKEiDmX&
grant_type=authorization_code&
redirect_uri=https://app.example.com/cb&
code=KIV31WkDhY6XIWXmWAc6U
code_verifier=fasdfads7645fassd33asddfasdf

grant_type=client_credentials

Assume these parameters:

Use dark colors for code blocksCopy
1
2
3
client_id=GGjeDjEY6kKEiDmX&
grant_type=client_credentials&
client_secret=57e2f75cd56346bf9d5654c3338a1250

grant_type=exchange_refresh_token

Assume these parameters:

Use dark colors for code blocksCopy
1
2
3
4
client_id=GGjeDjEY6kKEiDmX&
grant_type=exchange_refresh_token&
redirect_uri=https://app.example.com/cb&
refresh_token=GysTpIui-oxWTTIs

grant_type=refresh_token

Assume these parameters:

Use dark colors for code blocksCopy
1
2
3
client_id=GGjeDjEY6kKEiDmX&
grant_type=refresh_token&
refresh_token=GysTpIui-oxWTTIs

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.