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/

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

ParameterRequiredFormatDescription
client_idstringYour application's client_id.
redirect_uristringThe redirect_uri configured in step 2. The user will be redirected to this endpoint with the authorization code.
response_typestring ("code")The response type ("code" to receive an authorization code).
code_challengestringA locally generated string used in PKCE authorization.
expirationnumberThe duration that the eventual refresh token will remain valid.

Example

Use dark colors for code blocksCopy
1
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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
<!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
1
2

<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

ParameterRequiredFormatDescription
client_idstringYour application's client_id.
redirect_uristringThe redirect_uri configured in step 2. The user will be redirected to this endpoint with the access token.
response_typestring ("token")The response type ("token" to receive an access token).
expirationnumberThe duration that the resulting access token will remain valid.

Example

Use dark colors for code blocksCopy
1
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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
<!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
1
2

<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/

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.

ParameterRequiredFormatDescription
grant_typestring ("authorization_code")The OAuth 2.0 grant type of the request.
codestringThe authorization code.
client_idstringYour application's client_id.
redirect_uristringThe redirect_uri used in the previous request to the authorization endpoint.
code_verifierstringA locally generated string based on a code_challenge. It is used in PKCE authorization.

Response

Use dark colors for code blocksCopy
1
2
3
4
5
6
{
    "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.

ParameterRequiredFormatDescription
grant_typestring ("client_credentials")The OAuth 2.0 grant type of the request.
client_idstringYour application's client ID.
client_secretstringYour application's client secret.

Response

Use dark colors for code blocksCopy
1
2
3
4
{
    "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
1
2
3
4
5
6
7
{
    "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.

ParameterRequiredFormatDescription
grant_typestring ("refresh_token")The OAuth 2.0 grant type of the request.
client_idstringYour application's client ID.
refresh_tokenstringThe 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
1
2
3
4
{
    "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.

ParameterRequiredFormatDescription
client_idstringYour application's client ID.
grant_typerefresh_tokenYou must include this OAuth 2.0 grant type.
refresh_tokenstringThe previous refresh token issued alongside an access token.
redirect_uristringThe 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

Request parameters

ParameterRequiredFormatDescription
usernamestringThe username of the user's ArcGIS account.
codestringThe password of the user's ArcGIS account.
clientstring
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.
referrerstringThe base URL of the client application that will use the token.
ipstringThe IP address that will be using the created token for access.

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