Skip To Content

/token: Token

  • URL: https://[root]/oauth2/token

Example Usage

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 type Required 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

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

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

client_secret=57e2f75cd56346bf9d5654c3338a1250
code

(Required when grant_type=authorization_code)

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

Example

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

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

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:


{
  "error": {
    "code": 400,
    "error": "invalid_request",
    "error_description": "Invalid PKCE code_challenge_verifier",
    "message": "Invalid PKCE code_challenge_verifier",
    "details": []
  }
}

Response

{
  "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:

https://www.arcgis.com/sharing/rest/oauth2/token

grant_type=authorization_code

Assume these parameters:

client_id=GGjeDjEY6kKEiDmX&
grant_type=authorization_code&
redirect_uri=https://app.example.com/cb&
code=KIV31WkDhY6XIWXmWAc6U

PKCE flow

Assume these parameters:

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:

client_id=GGjeDjEY6kKEiDmX&
grant_type=client_credentials&
client_secret=57e2f75cd56346bf9d5654c3338a1250

grant_type=exchange_refresh_token

Assume these parameters:

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:

client_id=GGjeDjEY6kKEiDmX&
grant_type=refresh_token&
refresh_token=GysTpIui-oxWTTIs