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_
to token
.
Navigating to the authorization endpoint with a valid client_
and redirect_
will open a sign-in page that prompts users to enter the credentials of their ArcGIS account.
https:
https:
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_
parameter in the authorization request.
Required parameters
Parameter | Required | Format | Description |
---|---|---|---|
client_ | ✓ | string | Your application's client_ . |
redirect_ | ✓ | string | The redirect_ configured in step 2. The user will be redirected to this endpoint with the authorization code. |
response_ | ✓ | string ("code") | The response type ("code" to receive an authorization code). |
code_ | string | A locally generated string used in PKCE authorization. | |
expiration | number | The duration that the eventual refresh token will remain valid. |
Example
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.
<!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">
Successfully signing in with an ArcGIS account will redirect the browser to the provided redirect_
with an authorization code attached to the URL as a search parameter.
<REDIRECT_URI>?code=<AUTHORIZATION_CODE>
Access token (implicit)
The authorization endpoint can also grant an access token directly by setting the response_
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_ | ✓ | string | Your application's client_ . |
redirect_ | ✓ | string | The redirect_ configured in step 2. The user will be redirected to this endpoint with the access token. |
response_ | ✓ | string ("token") | The response type ("token" to receive an access token). |
expiration | number | The duration that the resulting access token will remain valid. |
Example
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.
<!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">
Successfully signing in with an ArcGIS account will redirect the browser to the provided redirect_
with an authorization code attached to the URL as a query parameter.
<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_
parameter will vary based on the type of request being made.
https:
https:
Access token from authorization code
To obtain an access token with an authorization code, the grant_
parameter must be set to authorization_
. 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_
parameter in the requestAnimationFrame. The code_
value must correspond to the code_
value provided to the authorization endpoint.
Required parameters
All request parameters should be form encoded
.
Parameter | Required | Format | Description |
---|---|---|---|
grant_ | ✓ | string ("authorization_code") | The OAuth 2.0 grant type of the request. |
code | ✓ | string | The authorization code. |
client_ | ✓ | string | Your application's client_id. |
redirect_ | ✓ | string | The redirect_ used in the previous request to the authorization endpoint. |
code_ | string | A locally generated string based on a code_ . It is used in PKCE authorization. |
Response
{
"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_
, expires_
(number of seconds until the access_
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_
parameter must be set to client_
. This grant is used to implement app authentication.
Required parameters
All request parameters should be form encoded
.
Parameter | Required | Format | Description |
---|---|---|---|
grant_ | ✓ | string ("client_credentials") | The OAuth 2.0 grant type of the request. |
client_ | ✓ | string | Your application's client ID. |
client_ | ✓ | string | Your application's client secret. |
Response
{
"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_
and try your request again.
{
"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_
parameter must be set to refresh_
.
All request parameters should be form encoded
.
Parameter | Required | Format | Description |
---|---|---|---|
grant_ | ✓ | string ("refresh_token") | The OAuth 2.0 grant type of the request. |
client_ | ✓ | string | Your application's client ID. |
refresh_ | ✓ | string | The refresh token previously issued with an access token. |
Response
In the response you will receive an access_
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.
{
"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_
parameter must be set to exchange_
.
Required parameters
All request parameters should be form encoded
.
Parameter | Required | Format | Description |
---|---|---|---|
client_ | ✓ | string | Your application's client ID. |
grant_ | ✓ | refresh_ | You must include this OAuth 2.0 grant type. |
refresh_ | ✓ | string | The previous refresh token issued alongside an access token. |
redirect_ | ✓ | string | The redirect_ specified during the authorization step. |
Generate token endpoint
The generate token endpoint is used in Generate token user authentication flows.
https:
https:
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. |