Server-based workflow

In this server-based 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 implementing user authentication, 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).

1. Direct your user to the authorization endpoint in a browser with the client_id, response_type=code, a redirect_uri, and an optional expiration.
2. 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.
3. Your application exchanges the authorization code for an access_token from the token endpoint. This requires the following:
   • Your application's client_id and client_secret
   • A grant_type = authorization_code
   • The redirect_uri from step 1
   • The authorization code provided in the previous step
4. Once you receive the access_token, it must be included in all subsequent requests that require a token.

Process details

Configure the redirect URI

1. Sign into your dashboard and click the OAuth 2.0 tab.

   

2. Follow the steps in the Add a redirect URI tutorial. This is where the authorization code is sent after the user has provided credentials.

   More info

   You can also configure a redirect URI in ArcGIS Online or ArcGIS Enterprise.

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

Authorization parameters

Authorization example

1
https://www.arcgis.com/sharing/rest/oauth2/authorize?client_id=<CLIENT_ID>&response_type=code&expiration=<N_SECONDS>&redirect_uri=<REDIRECT_URI>

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:

1
my-arcgis-app://auth?code=KYv4VCRymwC3UeD4-U9jkwGPHIoGqZ9SpDTBHwcE_pUmZquQRusn99YiXvUjlAmUJi42Wrh1hnlcy9RtZdfC_dnLrqu3PLWETQsyy-YVYuhLHSWKYiRKozx0eng5r0t70W_S-rlljdc0j8f-V5FI4vOkpKp0hMVgDG8pGsBZG8DYXnWdpYvDQCjIacIzFqz-vTt8FlXJZESmUC2wz2p_hQ..

You can now exchange this code with the token endpoint for a user's access_token.

Token endpoints

Request parameters

All request parameters should be form encoded.

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.

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'
}

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.

1
2
3
4
5
6
7
{
    "error": {
        "code": 498,
        "message": "Invalid Token",
        "details": []
    }
}

Refresh request parameters

All request parameters should be form encoded.

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.

1
2
3
4
5
{
    "access_token": "J-S0KLOl5_8UIqzZfmjPp6KQQeN5rnDRxRKB73n7B2hxuuI6Fec09IsIk0n8a0j-LoBskkio0I5fL0sY5iLf1J8lfhgq1gdaOAB15sm2wEaRooZbWz87bWptfGOMlqfFCoGRwF9n0h3tOd21lMyB9g..",
    "expires_in": 1800,
    "username": "username"
}