REST authentication operations

All user authentication and app authentication workflows are powered by REST endpoints of a portal service. The following endpoints are used to authorize, grant, and manage access tokens.

Authorization endpoint

The authorization endpoint is a security endpoint found at the URL /oauth2/authorize/ in a portal service. It is primarily used to obtain an authorization code in OAuth 2.0 user authentication flows. The authorization endpoint can also grant access tokens directly by setting the response_type to token.

Navigating to the authorization endpoint with a valid client_id and redirect_uri will open a sign-in page that prompts users to enter the credentials of their ArcGIS account.

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

https://<host>:<port>/<subdirectory>/sharing/rest/oauth2/authorize/

Authorization code

The authorization endpoint is primarily used to request an authorization code, which is used to obtain an access token in most user authentication flows.

When implementing user authentication in client applications, it is recommended to implement Proof Key for Code Exchange (PKCE) by including a locally generated code_challenge parameter in the authorization request.

Required parameters

Parameter	Required	Format	Description
`client_id`	✓	`string`	Your application's `client_id`.
`redirect_uri`	✓	`string`	The `redirect_uri` configured in step 2. The user will be redirected to this endpoint with the authorization code.
`response_type`	✓	`string` ("code")	The response type ("code" to receive an authorization code).
`code_challenge`		`string`	A locally generated string used in PKCE authorization.
`expiration`		`number`	The duration that the eventual refresh token will remain valid.

Example

Use dark colors for code blocksCopy
https://www.arcgis.com/sharing/rest/oauth2/authorize?client_id=<CLIENT_ID>&response_type=code&redirect_uri=<REDIRECT_URI>&code_challenge=<CODE_CHALLENGE>

Response

The endpoint will return a formatted HTML page that prompts a user to sign in with their ArcGIS account.

Use dark colors for code blocksCopy
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <meta name="referrer" content="origin">
    <title>Sign In</title>
    <script src="/sharing/files/scripts/detector.min.js?v=1B32B79"></script>
    <link rel="stylesheet" href="/sharing/files/css/site.min.css?v=1B32B79">
Expand

Successfully signing in with an ArcGIS account will redirect the browser to the provided redirect_uri with an authorization code attached to the URL as a search parameter.

Use dark colors for code blocksCopy

<REDIRECT_URI>?code=<AUTHORIZATION_CODE>

Access token (implicit)

The authorization endpoint can also grant an access token directly by setting the response_type to token. This is used in the implicit flow of user authentication, which has been deprecated as it is considered insecure.

Required parameters

Parameter	Required	Format	Description
`client_id`	✓	`string`	Your application's `client_id`.
`redirect_uri`	✓	`string`	The `redirect_uri` configured in step 2. The user will be redirected to this endpoint with the access token.
`response_type`	✓	`string` ("token")	The response type ("token" to receive an access token).
`expiration`		`number`	The duration that the resulting access token will remain valid.

Example

Use dark colors for code blocksCopy
https://www.arcgis.com/sharing/rest/oauth2/authorize?client_id=<CLIENT_ID>&response_type=token&redirect_uri=<REDIRECT_URI>

Response

The endpoint will return a formatted HTML page that prompts a user to sign in with their ArcGIS account.

Use dark colors for code blocksCopy
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <meta name="referrer" content="origin">
    <title>Sign In</title>
    <script src="/sharing/files/scripts/detector.min.js?v=1B32B79"></script>
    <link rel="stylesheet" href="/sharing/files/css/site.min.css?v=1B32B79">
Expand

Successfully signing in with an ArcGIS account will redirect the browser to the provided redirect_uri with an access token attached to the URL as a query parameter.

Use dark colors for code blocksCopy

<REDIRECT_URI>&token=<YOUR_ACCESS_TOKEN>

Token endpoint

The oauth2/token/ endpoint grants an access token when queried with a valid authorization code, client secret, or refresh token. The grant_type parameter will vary based on the type of request being made.

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

https://<host>:<port>/<subdirectory>/sharing/rest/oauth2/token

Access token from authorization code

To obtain an access token with an authorization code, the grant_type parameter must be set to authorization_code. This is the most commonly implemented grant type for user authentication flows, and is the type used (with PKCE) in all ArcGIS APIs and SDKs.

When implementing user authentication in client applications, it is recommended to implement Proof Key for Code Exchange (PKCE) by including a locally generated code_verifier parameter in the requestAnimationFrame. The code_verifier value must correspond to the code_challenge value provided to the authorization endpoint.

Required parameters

All request parameters should be form encoded.

Parameter	Required	Format	Description
`grant_type`	✓	`string` ("authorization_code")	The OAuth 2.0 grant type of the request.
`code`	✓	`string`	The authorization code.
`client_id`	✓	`string`	Your application's client_id.
`redirect_uri`	✓	`string`	The `redirect_uri` used in the previous request to the authorization endpoint.
`code_verifier`		`string`	A locally generated string based on a `code_challenge`. It is used in PKCE authorization.

Response

Use dark colors for code blocksCopy
{
    "access_token": "J-S0KLOl5_8UIqzZfmjPp6KQQeN5rnDRxRKB73n7B2hxuuI6Fec09IsIk0n8a0j-LoBskkio0I5fL0sY5iLf1J8lfhgq1gdaOAB15sm2wEaRooZbWz87bWptfGOMlqfFCoGRwF9n0h3tOd21lMyB9g..",
    "expires_in": 1800,
    "refresh_token": "gbY49hl4mGXJrw3kEf7P_nIkIK8X3zyiZJxvo8uawXGkSx3BuP5DlefcQSiNQKbZFu9RQb1GV2WpxH1GCvz0wbp0fv3RYkCran-UD6cS8nzIaUbA9PqzYrgPTsMSmhDbH-1eJPRaM_MspSVVCFbpBoaf-xHYoamU9rW76NSc2uJIeqClskbjzy-1NUiTXwM6blTGtdn4tw7ew8451ZHs8FRijLR0bNPGf_2XOm1aeJLi_MsXP7WGOy-5dDvDS2Y_GHEeUa3eN030_KghXbz98k6QcJXd0q83mPVkoIrcBtEapsImMgpc-b5mUQoNgYaV",
    "username": "sampleuser"
}

The response object will contain an access_token, expires_in (number of seconds until the access_token expires), and the universally unique username.

Access token from client credentials

To obtain an access token using a client ID and client secret, the grant_type parameter must be set to client_credentials. This grant is used to implement app authentication.

Required parameters

All request parameters should be form encoded.

Parameter	Required	Format	Description
`grant_type`	✓	`string` ("client_credentials")	The OAuth 2.0 grant type of the request.
`client_id`	✓	`string`	Your application's client ID.
`client_secret`	✓	`string`	Your application's client secret.

Response

Use dark colors for code blocksCopy
{
    "access_token": "J-S0KLOl5_8U***lMyB9g..",
    "expires_in": 86400
}

Refresh an access token

When a token expires, you will receive the following response. This typically means that your token has expired or is invalid. If you have a refresh token, you can get a new access_token and try your request again.

Use dark colors for code blocksCopy
{
    "error": {
        "code": 498, // May also be '499'
        "message": "Invalid Token",
        "details": []
    }
}

Required parameters

To regenerate an existing access token using a refresh token, the grant_type parameter must be set to refresh_token.

All request parameters should be form encoded.

Parameter	Required	Format	Description
`grant_type`	✓	`string` ("refresh_token")	The OAuth 2.0 grant type of the request.
`client_id`	✓	`string`	Your application's client ID.
`refresh_token`	✓	`string`	The refresh token previously issued with an access token.

Response

In the response you will receive an access_token for the user; you will not receive a new refresh token. If their refresh token expires, the user must instead go through the full sign in process.

Use dark colors for code blocksCopy
{
    "access_token": "J-S0KLOl5_8UIqzZfmjPp6KQQeN5rnDRxRKB73n7B2hxuuI6Fec09IsIk0n8a0j-LoBskkio0I5fL0sY5iLf1J8lfhgq1gdaOAB15sm2wEaRooZbWz87bWptfGOMlqfFCoGRwF9n0h3tOd21lMyB9g..",
    "expires_in": 1800
}

Exchange a refresh token

To exchange an old refresh token for a new one, the grant_type parameter must be set to exchange_refresh_token.

Required parameters

All request parameters should be form encoded.

Parameter	Required	Format	Description
`client_id`	✓	`string`	Your application's client ID.
`grant_type`	✓	`refresh_token`	You must include this OAuth 2.0 grant type.
`refresh_token`	✓	`string`	The previous refresh token issued alongside an access token.
`redirect_uri`	✓	`string`	The `redirect_uri` specified during the authorization step.

Generate token endpoint

The generate token endpoint is used in Generate token user authentication flows.

https://www.arcgis.com/sharing/rest/generateToken

https://<host>:<port>/<subdirectory>/sharing/rest/generateToken

Request parameters

Parameter	Required	Format	Description
`username`	✓	`string`	The username of the user's ArcGIS account.
`code`	✓	`string`	The password of the user's ArcGIS account.
`client`	✓	`string` Accepted values: `ip`, `referer`, `requestip`	The client type that will be granted access to the token. The token will be generated for a client application's base URL, a user-specified IP address, or the IP address that is making the request.
`referrer`		`string`	The base URL of the client application that will use the token.
`ip`		`string`	The IP address that will be using the created token for access.