REST authentication operations | Documentation

All user authenticationUser authentication is a type of authentication that allows users with an ArcGIS account to sign into an application and allow it to access ArcGIS content, services, and resources on their behalf. The typical authorization protocol used is OAuth2.0.Learn more and app authenticationApp authentication is a type of authentication that grants a short-lived access token based on an OAuth 2.0 client ID and client secret, authorizing an application to access ArcGIS services and items.Learn more workflows are powered by REST endpoints of a portal serviceA portal service provides the functionality to securely create, access, and manage content, data services, users, and groups in a portal. The service can be hosted by Esri or in ArcGIS Enterprise.Learn more. The following endpoints are used to authorize, grant, and manage access tokensAn access token is an authorization string that provides access to secure ArcGIS content, data, and services. Its capabilities are determined by the privileges it supports. It is obtained by implementing API key authentication, User authentication, or App authentication.Learn more.

Authorization endpoint

The authorization endpoint is a security endpoint found at the URL /oauth2/authorize/ in a portal serviceA portal service provides the functionality to securely create, access, and manage content, data services, users, and groups in a portal. The service can be hosted by Esri or in ArcGIS Enterprise.Learn more. It is primarily used to obtain an authorization codeAn authorization code is a string that is used to obtain an access token associated with a user account. It is required in user authentication flows that adhere to the OAuth2.0 authorization_code grant type.Learn more in OAuth 2.0 user authenticationUser authentication is a type of authentication that allows users with an ArcGIS account to sign into an application and allow it to access ArcGIS content, services, and resources on their behalf. The typical authorization protocol used is OAuth2.0.Learn more flows. The authorization endpoint can also grant access tokensAn access token is an authorization string that provides access to secure ArcGIS content, data, and services. Its capabilities are determined by the privileges it supports. It is obtained by implementing API key authentication, User authentication, or App authentication.Learn more directly by setting the response_type to token.

Navigating to the authorization endpoint with a valid client_id and redirect_uri will open a sign-in page that prompts users to enter the credentials of their ArcGIS accountAn ArcGIS account is an identity with a user type and set of privileges that can access specific ArcGIS products, tools, APIs, services, and resources. The main account types that can be used for development are an ArcGIS Location Platform account, ArcGIS Online account, and ArcGIS Enterprise account. ArcGIS Location Platform and ArcGIS Online accounts are also associated with a subscription.Learn more.

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

https://<host>:<port>/<subdirectory>/sharing/rest/oauth2/authorize/

Authorization code

The authorization endpoint is primarily used to request an authorization codeAn authorization code is a string that is used to obtain an access token associated with a user account. It is required in user authentication flows that adhere to the OAuth2.0 authorization_code grant type.Learn more, which is used to obtain an access tokenAn access token is an authorization string that provides access to secure ArcGIS content, data, and services. Its capabilities are determined by the privileges it supports. It is obtained by implementing API key authentication, User authentication, or App authentication.Learn more in most user authenticationUser authentication is a type of authentication that allows users with an ArcGIS account to sign into an application and allow it to access ArcGIS content, services, and resources on their behalf. The typical authorization protocol used is OAuth2.0.Learn more flows.

When implementing user authentication in client applications, it is recommended to implement Proof Key for Code Exchange (PKCE) by including a locally generated code_challenge parameter in the authorization request.

Required 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`	✓	`string` ("code")	The response type ("code" to receive an authorization codeAn authorization code is a string that is used to obtain an access token associated with a user account. It is required in user authentication flows that adhere to the OAuth2.0 `authorization_code` grant type.Learn more).
`code_challenge`		`string`	A locally generated string used in PKCE authorization.
`expiration`		`number`	The duration that the eventual refresh tokenA refresh token is a string obtained from user authentication that can be used to exchange an existing access token for a new one. The new access token has a new expiration date and possesses the same duration and level of authorization as the old token.Learn more will remain valid.

Example

Use dark colors for code blocksCopy
https://www.arcgis.com/sharing/rest/oauth2/authorize?client_id=<CLIENT_ID>&response_type=code&redirect_uri=<REDIRECT_URI>&code_challenge=<CODE_CHALLENGE>

Response

The endpoint will return a formatted HTML page that prompts a user to sign in with their ArcGIS accountAn ArcGIS account is an identity with a user type and set of privileges that can access specific ArcGIS products, tools, APIs, services, and resources. The main account types that can be used for development are an ArcGIS Location Platform account, ArcGIS Online account, and ArcGIS Enterprise account. ArcGIS Location Platform and ArcGIS Online accounts are also associated with a subscription.Learn more.

Use dark colors for code blocksCopy
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <meta name="referrer" content="origin">
    <title>Sign In</title>
    <script src="/sharing/files/scripts/detector.min.js?v=1B32B79"></script>
    <link rel="stylesheet" href="/sharing/files/css/site.min.css?v=1B32B79">
Expand

Successfully signing in with an ArcGIS account will redirect the browser to the provided redirect_uri with an authorization codeAn authorization code is a string that is used to obtain an access token associated with a user account. It is required in user authentication flows that adhere to the OAuth2.0 authorization_code grant type.Learn more attached to the URL as a search parameter.

Use dark colors for code blocksCopy

<REDIRECT_URI>?code=<AUTHORIZATION_CODE>

Access token (implicit)

The authorization endpoint can also grant an access tokenAn access token is an authorization string that provides access to secure ArcGIS content, data, and services. Its capabilities are determined by the privileges it supports. It is obtained by implementing API key authentication, User authentication, or App authentication.Learn more directly by setting the response_type to token. This is used in the implicit flow of user authenticationUser authentication is a type of authentication that allows users with an ArcGIS account to sign into an application and allow it to access ArcGIS content, services, and resources on their behalf. The typical authorization protocol used is OAuth2.0.Learn more, which has been deprecated as it is considered insecure.

Required 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 access token.
`response_type`	✓	`string` ("token")	The response type ("token" to receive an access tokenAn access token is an authorization string that provides access to secure ArcGIS content, data, and services. Its capabilities are determined by the privileges it supports. It is obtained by implementing API key authentication, User authentication, or App authentication.Learn more).
`expiration`		`number`	The duration that the resulting access tokenAn access token is an authorization string that provides access to secure ArcGIS content, data, and services. Its capabilities are determined by the privileges it supports. It is obtained by implementing API key authentication, User authentication, or App authentication.Learn more will remain valid.

Example

Use dark colors for code blocksCopy
https://www.arcgis.com/sharing/rest/oauth2/authorize?client_id=<CLIENT_ID>&response_type=token&redirect_uri=<REDIRECT_URI>

Response

Use dark colors for code blocksCopy
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <meta name="referrer" content="origin">
    <title>Sign In</title>
    <script src="/sharing/files/scripts/detector.min.js?v=1B32B79"></script>
    <link rel="stylesheet" href="/sharing/files/css/site.min.css?v=1B32B79">
Expand

Successfully signing in with an ArcGIS account will redirect the browser to the provided redirect_uri with an access token attached to the URL as a query parameter.

Use dark colors for code blocksCopy

<REDIRECT_URI>&token=<YOUR_ACCESS_TOKEN>

Token endpoint

The oauth2/token/ endpoint grants an access tokenAn access token is an authorization string that provides access to secure ArcGIS content, data, and services. Its capabilities are determined by the privileges it supports. It is obtained by implementing API key authentication, User authentication, or App authentication.Learn more when queried with a valid authorization code, client secret, or refresh token. The grant_type parameter will vary based on the type of request being made.

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

https://<host>:<port>/<subdirectory>/sharing/rest/oauth2/token

Access token from authorization code

To obtain an access token with an authorization code, the grant_type parameter must be set to authorization_code. This is the most commonly implemented grant type for user authenticationUser authentication is a type of authentication that allows users with an ArcGIS account to sign into an application and allow it to access ArcGIS content, services, and resources on their behalf. The typical authorization protocol used is OAuth2.0.Learn more flows, and is the type used (with PKCE) in all ArcGIS APIs and SDKs.

When implementing user authentication in client applications, it is recommended to implement Proof Key for Code Exchange (PKCE) by including a locally generated code_verifier parameter in the requestAnimationFrame. The code_verifier value must correspond to the code_challenge value provided to the authorization endpoint.

Required parameters

All request parameters should be form encoded.

Parameter	Required	Format	Description
`grant_type`	✓	`string` ("authorization_code")	The OAuth 2.0 grant type of the request.
`code`	✓	`string`	The authorization codeAn authorization code is a string that is used to obtain an access token associated with a user account. It is required in user authentication flows that adhere to the OAuth2.0 `authorization_code` grant type.Learn more.
`client_id`	✓	`string`	Your application's client_idOAuth credentials are an item that contains parameters required to implement user authentication or app authentication, including a `client_id`, `client_secret`, and redirect URIs. They are a type of developer credential.Learn more.
`redirect_uri`	✓	`string`	The `redirect_uri` used in the previous request to the authorization endpoint.
`code_verifier`		`string`	A locally generated string based on a `code_challenge`. It is used in PKCE authorization.

Response

Use dark colors for code blocksCopy
{
    "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"
}

The response object will contain an access_token, expires_in (number of seconds until the access_token expires), and the universally unique username.

Access token from client credentials

To obtain an access token using a client ID and client secretOAuth credentials are an item that contains parameters required to implement user authentication or app authentication, including a client_id, client_secret, and redirect URIs. They are a type of developer credential.Learn more, the grant_type parameter must be set to client_credentials. This grant is used to implement app authenticationApp authentication is a type of authentication that grants a short-lived access token based on an OAuth 2.0 client ID and client secret, authorizing an application to access ArcGIS services and items.Learn more.

Required parameters

All request parameters should be form encoded.

Parameter	Required	Format	Description
`grant_type`	✓	`string` ("client_credentials")	The OAuth 2.0OAuth 2.0 is an industry standard protocol for authorization. It defines how to obtain and manage credentials for web, desktop, and mobile applications. It is supported by ArcGIS.Learn more grant type of the request.
`client_id`	✓	`string`	Your application's client IDOAuth credentials are an item that contains parameters required to implement user authentication or app authentication, including a `client_id`, `client_secret`, and redirect URIs. They are a type of developer credential.Learn more.
`client_secret`	✓	`string`	Your application's client secretOAuth credentials are an item that contains parameters required to implement user authentication or app authentication, including a `client_id`, `client_secret`, and redirect URIs. They are a type of developer credential.Learn more.

Response

Use dark colors for code blocksCopy
{
    "access_token": "J-S0KLOl5_8U***lMyB9g..",
    "expires_in": 86400
}

Refresh an access token

When a token expires, you will receive the following response. This typically means that your token has expired or is invalid. If you have a refresh token, you can get a new access_token and try your request again.

Use dark colors for code blocksCopy
{
    "error": {
        "code": 498, // May also be '499'
        "message": "Invalid Token",
        "details": []
    }
}

Required parameters

To regenerate an existing access tokenAn access token is an authorization string that provides access to secure ArcGIS content, data, and services. Its capabilities are determined by the privileges it supports. It is obtained by implementing API key authentication, User authentication, or App authentication.Learn more using a refresh token, the grant_type parameter must be set to refresh_token.

All request parameters should be form encoded.

Parameter	Required	Format	Description
`grant_type`	✓	`string` ("refresh_token")	The OAuth 2.0OAuth 2.0 is an industry standard protocol for authorization. It defines how to obtain and manage credentials for web, desktop, and mobile applications. It is supported by ArcGIS.Learn more grant type of the request.
`client_id`	✓	`string`	Your application's client IDOAuth credentials are an item that contains parameters required to implement user authentication or app authentication, including a `client_id`, `client_secret`, and redirect URIs. They are a type of developer credential.Learn more.
`refresh_token`	✓	`string`	The refresh tokenA refresh token is a string obtained from user authentication that can be used to exchange an existing access token for a new one. The new access token has a new expiration date and possesses the same duration and level of authorization as the old token.Learn more previously issued with an access token.

Response

In the response you will receive an access_token for the user; you will not receive a new refresh token. If their refresh token expires, the user must instead go through the full sign in process.

Use dark colors for code blocksCopy
{
    "access_token": "J-S0KLOl5_8UIqzZfmjPp6KQQeN5rnDRxRKB73n7B2hxuuI6Fec09IsIk0n8a0j-LoBskkio0I5fL0sY5iLf1J8lfhgq1gdaOAB15sm2wEaRooZbWz87bWptfGOMlqfFCoGRwF9n0h3tOd21lMyB9g..",
    "expires_in": 1800
}

Exchange a refresh token

To exchange an old refresh token for a new one, the grant_type parameter must be set to exchange_refresh_token.

Required parameters

All request parameters should be form encoded.

Parameter	Required	Format	Description
`client_id`	✓	`string`	Your application's client IDOAuth credentials are an item that contains parameters required to implement user authentication or app authentication, including a `client_id`, `client_secret`, and redirect URIs. They are a type of developer credential.Learn more.
`grant_type`	✓	`refresh_token`	You must include this OAuth 2.0 grant type.
`refresh_token`	✓	`string`	The previous refresh token issued alongside an access token.
`redirect_uri`	✓	`string`	The `redirect_uri` specified during the authorization step.

Generate token endpoint

The generate token endpoint is used in Generate token user authenticationUser authentication is a type of authentication that allows users with an ArcGIS account to sign into an application and allow it to access ArcGIS content, services, and resources on their behalf. The typical authorization protocol used is OAuth2.0.Learn more flows.

https://www.arcgis.com/sharing/rest/generateToken

https://<host>:<port>/<subdirectory>/sharing/rest/generateToken

Request parameters

Parameter	Required	Format	Description
`username`	✓	`string`	The username of the user's ArcGIS accountAn ArcGIS account is an identity with a user type and set of privileges that can access specific ArcGIS products, tools, APIs, services, and resources. The main account types that can be used for development are an ArcGIS Location Platform account, ArcGIS Online account, and ArcGIS Enterprise account. ArcGIS Location Platform and ArcGIS Online accounts are also associated with a subscription.Learn more.
`code`	✓	`string`	The password of the user's ArcGIS accountAn ArcGIS account is an identity with a user type and set of privileges that can access specific ArcGIS products, tools, APIs, services, and resources. The main account types that can be used for development are an ArcGIS Location Platform account, ArcGIS Online account, and ArcGIS Enterprise account. ArcGIS Location Platform and ArcGIS Online accounts are also associated with a subscription.Learn more.
`client`	✓	`string` Accepted values: `ip`, `referer`, `requestip`	The client type that will be granted access to the token. The token will be generated for a client application's base URL, a user-specified IP address, or the IP address that is making the request.
`referrer`		`string`	The base URL of the client application that will use the token.
`ip`		`string`	The IP address that will be using the created token for access.