Skip To Content
ArcGIS Developers
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 are typically used by JavaScript applications, and they 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.

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.

Request parameters

ParameterDetails
client_id

(Required)

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

Example

client_id=GGjeDjEY6kKEiDmX
response_type

(Required)

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

Values: token | code

Example

response_type=token
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
client_secret

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

Example

client_secret=57e2f75cd56346bf9d5654c3338a1250
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
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": []
    }
}

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

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
persist

A Binary value that, if true, implies that the user had checked "Keep me signed in" when signing into ArcGIS Online.

Values: true | false

ssl

A Binary value that, if true, implies that the user belongs to an SSL-only organization

Values: true | false

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