Request an Authorization Code

Endpoint URL: /{customerId}/login/authorize


Requests an authorization code from the authorization endpoint. 

The /{customer_id}/login/authorize endpoint is used to request an authorization code from the authorization endpoint. If this call succeeds, the client is given an authorization code; that code can then be presented to the token endpoint and exchanged for an access token, refresh token, and identity token.

If an authorization request is accepted, the user is presented with the sign-in screen and is asked to log on to the site or app. If authentication succeeds, the user will be fully logged on to the site, will be issued an access token, a refresh token, and an identity token, and then be redirected to the URL specified in the authorization request.

Note. That’s a slightly-abridged version of the authorization and authentication process. For a more-detailed version, see the article Authorization Code + PKCE.

A typical authorization request looks something like this:
  &scope=openid email phone

Note. A few carriage returns and blank spaces were added to the preceding request in order to make it easier to read. A real authorization request looks more like this: y63Qmobx6ZCSYCZqPNzQ6Qx1rGK0reaxgbb5WSAQR0o&code_challenge_method=S256&response_type=code &scope=openid%20email%20phone&state=tbXZO4Fkxy90JvJx0s2sbt-FsK2yNK0tqYrX4YvPjB4

The parameters used in the preceding authorization request, as well as additional parameters than can also be used in a request, are summarized in the table below:

Request Parameters

The query parameters for the /{customer_id}/login/authorize endpoint include the following:






Unique identifier of the OIDC login client used to make the authorization request. For example:




Specifies the type of response expected from the authorization server; at this point in time the Identity Cloud only supports the code response type. Note that this parameter is required even though there’s only one supported response type:


The code response indicates that the client expects to get an authorization code back following a successful authentication. In turn, the client exchanges that code for a set of tokens.



Specifies the OpenID Connect scopes to be accessible from the userinfo endpoint following a successful authentication and login. Note that you must include the scope parameter and, at a minimum, request the openid scope; this tells the authorization server that you want to authenticate by using OpenID Connect.

Other scopes supported by the Identity Cloud are detailed in the article OpenID Connect Scopes and Claims. You can request multiple scopes by separating each scope using a blank space:

scope=openid email profile

You can include any (or all) the supported scopes in your authentication request. However, that doesn’t mean that you’ll get back all of those scopes. Instead, the scopes made accessible from the userinfo endpoint depend on the value of the allowedScopes property found in the token policy applied during a user login. 

For example, suppose the allowedScopes property only specifies the openid and email scopes. In that case you can only get back those two scopes; any other scopes mentioned in your authorization request (such as profile or address) are ignored and are not returned.



Specifies the URL of the page the user is redirected to following a successful authentication and login. For example:


Note that the specified URL must be exactly match one of the URLs listed in the OIDC login client’s redirectURIs property. If the URL isn’t included in the redirectURIs property then the authorization request fails with an Invalid client error and the user will not be authenticated.


Yes (with PKCE)

Hashed and encoded value generated by the client. This value should be verified before the client is allowed to exchange an authorization code for a set of tokens.

For example:

code_challenge= RTg4QjMyRUJCNzdBRTQ1MkM2NTAzRTVDOEQ5OTg


Yes (with PKCE)

Hashing algorithm used to generate the value of the code_challenge parameter. For Hosted Login, this will always be S256:



No (but recommended) 

A random string that helps guard against cross-site request forgery (CSRF). For example, suppose your authentication includes the following state parameter and parameter value: 


After a successful authentication, you’ll be redirected to the URL specified by the redirect_uri parameter. If you were redirected by the authorization server then the state parameter and value will be included in the URI:

If the state parameter in the redirect URI doesn’t match your original parameter value then you might be the victim of CSFR attack (defined as an attack in which malware tries to trick you into carrying out some sort of action you never intended to carry out). In that case, you should restart the authentication process.



Specifies which screen (if any) is displayed when a user makes an authorization request. Allowed values are:

  • none. When prompt is set to none, Hosted Login first checks to see if the client has a valid session. If a valid session is found the user doesn't need to authenticate; instead, he or she is automatically logged in using the existing session. If a valid session can't be found a "No authenticated session found" error is generated and the user is not given the option of logging in.

    If you set the prompt parameter to none, it's recommended that you write code that: 1) looks for the "No authenticated session found" error ; and, 2) displays the sign-in screen. (If you don't, a user without an existing session would never be able to log in.) You might consider creating a cookie indicating that the user has been denied access because they didin't have a valid session. If you do that then, the next time user accesses your site , you'll know to employ an authorization request where the prompt is set to login (i.e., a request where the sign-in screen is always displayed).
  • login. The sign-in screen is always displayed first, even if a valid session is found. This ensures that users log in each time they access the site.
  • create. The traditional registration screen (used for creating new account) is always displayed first. Note, however, that the Sign In link isn’t found on the traditional registration screen. That means that setting the prompt to create represents a dead-end for existing users: they don’t need to create account, but they can’t log on using their existing account.

If this parameter isn't included then Hosted Login first checks to see if the client has a valid session. If a valid session exists the user doesn't need to authenticate; instead, he or she is automatically logged in using the existing session. If a valid session can't be found then the sign-in screen is displayed and the user can log in. 

For example:




Specifies the amount of time, in seconds, that can elapse before a user is required to reauthenticate. For example, suppose the max_age parameter is set to 3600 seconds (one hour). A user logs on, leaves the website, then returns 30 minutes later. Because the max_age limit of 1 hour has not been reached, the user will automatically be authenticated and resume their previous session.

Now, suppose a second user logs on, leaves the website, then comes back 2 hours later. because the max_age value has been exceeded, this user will be forced to reauthenticate.

Note that the max_age parameter applies only to logins. Suppose a third user logs on and stays on the site for 2 hours. That user will not be forced to reauthenticate halfway through their session. As noted, max_age only applies to logins.



Specifies the language/locale used when displaying Hosted Login login, registration, and user profile screens. Language preferences are passed as a space-delimited set of RFC 5646 language codes. For example:

ui_locales= fr-FR es-ES

In the preceding example, Hosted Login first tries to render screens by using French (fr-FR); if that fails, Hosted Login tries to render the screens by using Spanish (es-ES). If that fails, then Hosted Login defaults to displaying all screens in English.

Why would an attempt to render screens fail? This is almost always because you specified a language/locale that can’t be found in your flow: you can specify any language or locale that you want, but to actually display screens using that language/locale requires you to have the locale (and the accompanying translations) in your flow. See this article for more information.



Provides a way to prepopulate the email address field on the Hosted Login sign-in screen. In your authorization request, include the login_hint parameter followed by the email address of the user who needs to be authenticated. For example:

When you submit your authorization request, the email address will be included on the sign-in screen:

Note that Hosted Login cannot determine the email address to be included in the authorization request. Instead, you will need to use an alternate approach to determine the email address (for example, getting the email address when the user logs on to the computer) and then take the steps needed to add that address to the authorization request.



Specifies the claims (i.e., user profile attributes) to be included in the identity token or to be made accessible from the userinfo endpoint (or both). These claims can either be standard OpenID Connect claims (see OpenID Connect Scopes and Claims for more information) or custom claims created by your organization and defined in your login policies.

For example, this syntax makes the birthdate claim accessible from the userinfo endpoint:


Meanwhile, this syntax adds a custom claim named organization to the identity token:


And this syntax makes the organization claim accessible from the userinfo endpoint and adds that same claim to the identity token:

&claims={"userinfo":{"organization":null}, "id_token":{"organization":null}} 



Specifies where (and how) the sign-in screen is displayed. Allowed values are:

  • page (the default value)., When you submit your authorization request, you’ll be redirected to a separate page that contains the sign-in screen (and nothing but the sign-in screen). After you’ve successfully logged on you'll be redirected to the page specified in the redirectURIs property of your OIDC client.
  • popup. When you submit your authorization request you are not redirected to a standalone login page. Instead, the login page appears in a pop-up window, no redirection required. After you’ve successfully logged on then you’ll be redirected to the page specified in the redirectURIs property of your OIDC client.

For example:



No, but recommended

Helps ensure that the identity token you receive is the same identity token that you requested (in other words, you got back a token sent in direct response to your authentication request).

To use the nonce parameter, simply enter a random string in the Nonce field and then make your authentication request, When you decode the returned identity token, you should see a nonce property. The value in the identity token should be the same as the value included in your authentication request.


No authentication is required to call the /{customer_id}/login/authorize endpoint.

Sample Request 1: Authorization Code for Web Apps Flow (curl)

The following command uses the Authorization Code flow to request an authorization code from the endpoint

Sample Request 2: Authorization Code + PKCE Flow (curl)

The following command uses the Authorization Code + PKCE flow to request an authorization code from the endpoint To use PKCE, the code_challenge and code_challenge_method parameters were added to the previous authorization request. 3QjIwMjVBNTcxQTU5RTJFNDYwMzJBQjYxRkM4Nj Q0QzdBNw&code_challenge_method=S256


200 OK

If your call to this endpoint succeeds, you'll get back a response similar to the following. In this sample response, the authorization code has been highlighted in red: %url%

Note that you will get the same response back regardless of whether you are using the Authorization Code flow or the Authorization Code + PKCE flow. When using the Authorization Code + PKCE flow, no information about the code challenge or code challenge method are included in the response.