The server-side workflow offers the best combination of flexibility and security. Tokens obtained in this way last for 30 minutes but can be refreshed for a period defined by the user's organization (forever by default) and the client_secret acts as additional verification of the application.

Server Side App Login

  1. Direct your users to the authorization endpoint https://www.arcgis.com/sharing/rest/oauth2/authorize in a browser with your client_id, response_type=code, a redirect_uri and optional expiration.
  2. If the user successfully presents their username and password they will be redirected back to your application with an authorization code https://app.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA.
  3. Your application exchanges the authorization code for an access token from the token endpoint https://www.arcgis.com/sharing/rest/oauth2/token. This requires the following:
  • Your application's client_id and client_secret
  • A grant_type of authorization_code
  • The redirect_uri from step 1
  • The authorization code from the previous step
  1. Once you have the access token, include it in requests to ArcGIS Online which require a token.

Configure a redirect URI

  1. Go to the "Authentication" tab for your application on ArcGIS for Developers.

    Application Overview
  2. Add a new redirect URI to the list at the bottom of the page. These redirect URIs represent the valid places that a user can be redirected to after a successful sign in.

    Application Overview

Note: You can also configure a redirect URI on ArcGIS Online or in your own on-premise portal

3. Add a redirect URI that matches the handler you configured for your application in step 1. For example https://my-arcgis-app.com/oauth-callback. This is where the authorization code will be sent when the user has authorized it.

You can also register your applications on ArcGIS Online in your My Contents screen.

Send the User to the Authorization Screen

Now you need to open the authorization screen in a browser for the user to sign into. A browser is used for several reasons.

Authorization endpoint

ArcGIS Online: https://www.arcgis.com/sharing/rest/oauth2/authorize/
On-premise ArcGIS Portal: https://<host>:<port>/<subdirectory>/sharing/rest/oauth2/authorize

Authorization parameters

Parameter Required Description
client_id The client_id of your application.
redirect_uri The redirect_uri that you configured above. The user will be redirected to this endpoint with the authorization code.
response_type code The OAuth 2.0 grant type of code is required.
expiration Requested duration (in seconds) the refresh_token you will receive. You can specify -1 for a refresh_token that will last forever. ArcGIS Online organizations can override this with a shorter duration.

Authorization example

https://www.arcgis.com/sharing/rest/oauth2/authorize?client_id=YOUR_APPLICATIONS_CLIENT_ID&response_type=code&expiration=SECONDS&redirect_uri=REDIRECT_URI_CONFIGURED_ABOVE

Exchange the authorization code for an access token

Once the user authorizes your application the browser will redirect them to the provided redirect URL with the code, in this example:

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

You can now exchange the code for a user's access_token.

Token endpoint

ArcGIS Online: https://www.arcgis.com/sharing/rest/oauth2/token/
On-premise ArcGIS Portal: https://<host>:<port>/<subdirectory>/sharing/rest/oauth2/token

A token can be generated using only the POST method and only over HTTPS.

Request parameters

Parameter Required Description
client_id The client_id of your application.
code The authorization code.
redirect_uri The redirect_uri of that was used with this authorization code in the previous step.
grant_type authorization_code The OAuth 2.0 grant type of authorization_code is required.

All request parameters should be form encoded.

Response object

In the response you will receive an access_token, for the user as well as the number of seconds that access token will expire in. The expires_in key in the response is always the number of seconds the access_token will expire in not the refresh token. You will also receive the logged in user's username which is guaranteed to be unique across the entire platform.

{
    "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": 'bobgis'
}

Refreshing the token

The authorization code grant type recommends short lived access tokens and long lived refresh tokens. When a token expires you will receive the following response:

{
    "error": {
        "code": 498,
        "message": "Invalid Token",
        "details": []
    }
}

Note: The error.code property may also be 499.

When this occurs it usually 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.

Token endpoint

ArcGIS Online: https://www.arcgis.com/sharing/rest/oauth2/token/
On-premise ArcGIS Portal: https://<host>:<port>/<subdirectory>/sharing/rest/oauth2/token

A token can be generated using only the POST method and only over HTTPS.

Request parameters

Parameter Required Description
client_id The client_id of your application.
refresh_token The refresh token for this user.
grant_type refresh_token The OAuth 2.0 grant type of refresh_token is required.

All request parameters should be form encoded.

Response object

In the response you will receive an access_token for the user. You do not receive a new refresh token. If your refresh token expires you must perform the sign in process again.

{
    "access_token": "J-S0KLOl5_8UIqzZfmjPp6KQQeN5rnDRxRKB73n7B2hxuuI6Fec09IsIk0n8a0j-LoBskkio0I5fL0sY5iLf1J8lfhgq1gdaOAB15sm2wEaRooZbWz87bWptfGOMlqfFCoGRwF9n0h3tOd21lMyB9g..",
    "expires_in": 1800,
    "username": "username"
}

OAuth 2.0 helpers and libraries

Because OAuth 2.0 is a widely accepted web standard you can find many libraries that implement OAuth 2.0 on top of almost any common server framework. Below is a list of OAuth 2.0 implementations in common frameworks.

Node JS

Ruby