REST authentication operations

All and workflows are powered by REST endpoints of a . The following endpoints are used to authorize, grant, and manage .

Authorization endpoint

The authorization endpoint is a security endpoint found at the URL /oauth2/authorize/ in a . It is primarily used to obtain an in OAuth 2.0 flows. The authorization endpoint can also grant 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 .

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

Authorization code

The authorization endpoint is primarily used to request an , which is used to obtain an in most 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 ).
code_challengestringA locally generated string used in PKCE authorization.
expirationnumberThe duration that the eventual will remain valid.

Example

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 .

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 attached to the URL as a search parameter.

1
2

<REDIRECT_URI>?code=<AUTHORIZATION_CODE>

Access token (implicit)

The authorization endpoint can also grant an directly by setting the response_type to token. This is used in the implicit flow of , 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 ).
expirationnumberThe duration that the resulting will remain valid.

Example

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 .

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.

1
2

<REDIRECT_URI>&token=<YOUR_ACCESS_TOKEN>

Token endpoint

The oauth2/token/ endpoint grants an 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 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 .
client_idstringYour application's .
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

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 , the grant_type parameter must be set to client_credentials. This grant is used to implement .

Required parameters

All request parameters should be form encoded.

ParameterRequiredFormatDescription
grant_typestring ("client_credentials")The grant type of the request.
client_idstringYour application's .
client_secretstringYour application's .

Response

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.

1
2
3
4
5
6
7
{
    "error": {
        "code": 498, // May also be '499'
        "message": "Invalid Token",
        "details": []
    }
}

Required parameters

To regenerate an existing 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 grant type of the request.
client_idstringYour application's .
refresh_tokenstringThe 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.

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 .
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 flows.

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

Request parameters

ParameterRequiredFormatDescription
usernamestringThe username of the user's .
codestringThe password of the user's .
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.

You can no longer sign into this site. Go to your ArcGIS portal or the ArcGIS Location Platform dashboard to perform management tasks.

Your ArcGIS portal

Create, manage, and access API keys and OAuth 2.0 developer credentials, hosted layers, and data services.

Your ArcGIS Location Platform dashboard

Manage billing, monitor service usage, and access additional resources.

Learn more about these changes in the What's new in Esri Developers June 2024 blog post.

Close