Skip To Content
ArcGIS Developer
Dashboard

/authorize: Authorize

  • URL: https://[root]/oauth2/authorize(POST only)

Example Usage

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

Description

The Authentication topic describes the overall OAuth2 authentication flow. This topic describes the user authorization step of that flow.

Apps that support user logins use OAuth2 to allow users to log in to the ArcGIS platform via the app.

User logins using the OAuth2-based ArcGIS APIs are based on the application guiding the user to log in to the platform via a login page hosted on the ArcGIS platform. The authorize endpoint represents that login page. The login page renders an HTML form for the user to enter their credentials.

The user authentication workflow starts with the authorization step. Apps need to direct the browser to this URL. client_id, response_type, and redirect_uri are required parameters. There are other optional parameters as well, and they;'re described below.

The response_type parameter determines the type of grant—implicit or authorization. A response_type of token implies implicit grant and code implies authorization code grant.

Implicit grants complete the flow in a single step. The end result of successful authentication is an access_token that's delivered to the specified redirect_uri in the URL fragment. See the Response section for details. Implicit grant was typically used by JavaScript applications, but starting from March 2022 ArcGIS Online release, support for Proof Key for Code Exchange (PKCE) has been added. PKCE is an extension to authorization grant flow and is recommended for all the applications including the web applications.

Authorization grants are used by mobile, desktop, and server-side applications, and they complete the flow in two steps. Authorization represents the first step of that flow. Successful authorization yields an authorization code that's delivered to the specified redirect_uri as a query parameter. See the Response section for details. The second step of the flow requires exchanging the authorization code obtained in the first step for an access_token. This is accomplished by accessing the token endpoint with a grant_type of authorization_code. It is recommended to use Authorization grant with PKCE for all applications.

Request parameters

ParameterDetails
client_id

(Required)

The ID of the registered application. Also referred to as APPID.

Example

client_id=GGjeDjEY6kKEiDmX
redirect_uri

(Required)

The URI where the access_token or authorization code will be delivered upon successful authorization. The URI must match one of the URIs specified during app registration, otherwise authorization will be rejected. If registered, a special value of urn:ietf:wg:oauth:2.0:oob can also be specified for authorization grants. This will result in the authorization code being delivered to a portal URL (/oauth2/approval). This value is typically used by applications that don't have a web server or a custom URI scheme where the code can be delivered.

Example

redirect_uri=https://app.example.com/cb
response_type

(Required)

The type of grant, either implicit (token) or authorization (code).

Values: token | code

Example

response_type=token
client_secret

The secret of the registered application. Also referred to as APPSECRET.

Example

client_secret=57e2f75cd56346bf9d5654c3338a1250
code_challenge

The Base64-URL-encoded SHA256 hash of the client generated code verifier. The code verifier is a cryptographically random string using the characters A-Z, a-z, 0-9, and the punctuation characters -._~ (hyphen, period, underscore, and tilde), between 43 and 128 characters long.

Clients that do not have the ability to perform a SHA256 hash can use plain code verifier string as the code_challenge. Using plain code verifier provides less security benefits, so use only when necessary.

Example

code_challenge=abcdsasdf34efghabcdsasdf3aaab234asdf3aaartyrtdsasdf3aa
code_challenge_method

A value that shows whether the code_challenge is SHA256 hash or plain text. The default is plain.

If the value is set to plain, authorization server will perform an exact match of code_challenge and code challenge verifier. Using plain provides less security benefits, so use only when necessary.

Values: S256 | plain

Example

code_challenge_method=S256
display

The template used to render the login page. Based on the client platform, applications can choose one of the supported templates to render the login page. If not specified, the default template is used.

Values: default | iframe | win8

expiration

The requested validity in minutes of access_token for implicit grants or refresh_token for authorization grants. For implicit grants, the default validity of access_tokens is 120 minutes. The expiration parameter, if specified, overrides the validity period up to a max of 20160 minutes (2 weeks).

For authorization grants, the default validity of the access_token is 30 minutes and cannot be increased. The default validity of the refresh_token is 20160 minutes (2 weeks). The expiration parameter, if specified, overrides the validity period of the refresh_token up to a max of 90 days.

Example of two weeks

expiration=20160
Note:

Organization administrators can specify the max validity period of tokens for their org that supercedes the expiration parameter through the maxTokenExpirationMinutes parameter. An access_token can become invalid before it expires, as when a user changes their password. When it expires or is invalid, an error response like below will be returned:

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

locale

The locale assumed to render the login page. Applications can pass the user's locale using this parameter. The login page will be rendered using the language corresponding to that locale. If not specified, the locale will be determined based on the org's setting or on the incoming request.

Example

locale=fr
state

An opaque value used by applications to maintain state between authorization requests and responses. The state, if specified, will be delivered back to the redirect_uri as is. Applications can use this parameter to correlate the authorization request sent with the received response.

Example

state=qyxmpg9e5uWUPbxw
style

The color scheme used to render the login page regardless of browser or operating system preference. If not specified, it will follow the browser or OS preferred color scheme or light as the default style when there is no preference.

Values: light | dark

Response

Implicit grant

The access_token will be delivered to the specified redirect_uri in the URL fragment.

https://app.example.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA&expires_in=3600&state=qyxmpg9e5uWUPbxw

expires_in represents the token expiration in seconds from now.

Explicit grant

The authorization code will be delivered to the specified redirect_uri as a query parameter.

https://app.example.com/cb?code=KIV31WkDhY6XIWXmWAc6U&state=qyxmpg9e5uWUPbxw

If the special value of urn:ietf:wg:oauth:2.0:oob is specified as the redirect_uri, the authorization code will be delivered to a portal URL (/oauth2/approval). This URL will render an HTML page, and the code can be extracted from the <title> element of the page.

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

The <title> element of the rendered HTML page will include the code as:

<title>SUCCESS code=KIV31WkDhY6XIWXmWAc6U</title>

Example usage

For all examples, assume this endpoint:

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

Implicit grant

Assume these parameters:

client_id=GGjeDjEY6kKEiDmX&
response_type=token&
redirect_uri=https://app.example.com/cb

Explicit grant

Assume these parameters:

client_id=GGjeDjEY6kKEiDmX&
response_type=code&
redirect_uri=https://app.example.com/cb

for PKCE flow

Assume these parameters:

client_id=GGjeDjEY6kKEiDmX&
response_type=code&
redirect_uri=https://app.example.com/cb
code_challenge=asdfasf23423asdfasf234234asdf224asdfasdasdfg456dgffgh
code_challenge_method=S256