Server-enabled workflow
In this server-enabled OAuth 2.0 workflow, ArcGIS Online and ArcGIS Enterprise users sign in with their user name and password. Their credentials authorize your app to access any content and services authorized through the platform to that user, and the user is billed for any content and services they use. This process uses the OAuth 2.0 authorization_code
grant type.
Overview
This is possibly the most flexible and secure method for using ArcGIS identity, where the access_token
and client_secret
provide a two step authentication process. The initial access_token
expires in 30 minutes, but can be refreshed for a period defined by the user's organization (forever
by default).
- Direct your user to the authorization endpoint in a browser with the
client_id
,response_type=code
, aredirect_uri
, and an optionalexpiration
. - When the user successfully presents their username + password, they are redirected to your application with an appended authorization
code
, for example:https://app.example.com/cb?code=Splx123456
. - Your application exchanges the authorization
code
for anaccess_token
from the token endpoint. This requires the following:- Your application's
client_id
andclient_secret
- A
grant_type
=authorization_code
- The
redirect_uri
from step 1 - The authorization
code
provided in the previous step
- Your application's
- Once you receive the
access_token
, it must be included in all subsequent requests that require atoken
.
Process details
Configure the redirect URI
Sign into your dashboard and click the OAuth 2.0 tab.
Follow the steps in the Add a redirect URI tutorial. This is where the authorization
code
is sent after the user has provided credentials.
Get an authorization code
Direct your user to an authorization endpoint in a browser to sign in with their username + password, using the correct authorization parameters.
Authorization endpoints
https://www.arcgis.com/sharing/rest/oauth2/authorize/
https://<host>:<port>/<subdirectory>/sharing/rest/oauth2/authorize
Authorization 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 | ✓ | code | You must include this OAuth 2.0 response type. |
expiration | number | Requested duration (in seconds) of the refresh_token . -1 = a refresh_token that will last forever. ArcGIS Online organizations can override this with a shorter duration. |
Authorization example
Exchange the code for a token
Once the user authorizes your application, the browser will redirect them to the configured redirect URL with the appended authorization code
, in this example:
You can now exchange this code
with the token endpoint for a user's access_token
.
Token endpoints
https://www.arcgis.com/sharing/rest/oauth2/token/
https://<host>:<port>/<subdirectory>/sharing/rest/oauth2/token
Request parameters
All request parameters should be form encoded
.
Parameter | Required | Format | Description |
---|---|---|---|
client_id | ✓ | string | Your application's client_id . |
code | ✓ | string | The authorization code . |
redirect_uri | ✓ | string | The redirect_uri used with this authorization code in the previous step. |
grant_type | ✓ | authorization_code | You must include this OAuth 2.0 grant type. |
Response object
The response object will contain an access_token
, expires_in
(number of seconds until the access_token
expires), and the universally unique username
.
Refresh the token
The authorization code
grant type recommends short-lived access tokens and long-lived refresh tokens.
Error example
When a token expires, you receive the following response. This typically means that your token has expired or is invalid. If you have a refresh token from the previous step, you can get a new access_token
and try your request again.
Refresh request parameters
All request parameters should be form encoded
.
Parameter | Required | Format | Description |
---|---|---|---|
client_id | ✓ | string | Your application's client_id . |
refresh_token | ✓ | string | Your user's refresh token. |
grant_type | ✓ | refresh_token | You must include this OAuth 2.0 grant type. |
Response object
The response will contain an access_token
for the user; it will not contain a new refresh token. If your user's refresh token expires, they must sign in again.