Authorization code grant workflow

  • Release version: Zurich
  • Updated June 11, 2026
  • 5 minutes to read

    • The OAuth authorization code grant is a secure and widely used flow for web, mobile, or desktop apps that access user data with user consent. It supports both private clients (using a client secret), and public clients (using PKCE).

    Before you begin

    Role required: oauth_admin, mi_admin, admin

    About this task

    This topic collection provides information on how a client application can use the Authorization code grant flow to obtain a token from ServiceNow and make API calls with that token. Private clients use client secret, while public clients use PKCE code challenge.

    Figure 1. Authorization workflow
    Authorization Workflow

    Procedure

    1. Log in from the client application.

      The user begins the login process from the client application interface.

    2. Initiate the authorization request.

      The client redirects the user to the ServiceNow authorization endpoint. The method of initiating the authorization request depends on the type of client: Public or Private.

      Public Clients

      Public clients (Example: Mobile or Single-page applications) cannot securely store a client secret. Therefore, they must use Proof Key for Code Exchange (PKCE) to enhance security.

      • In the authorization request, include the PKCE code challenge and specify the code challenge method.
      • During the token request, the client must send the code verifier to validate the authorization code.
      Perform a GET request to the authorization endpoint with the following parameters:
      Method: GET
Endpoint: https://<servicenow_base_url>/oauth_auth.do
      Table 1. Authorization Request Parameters (Public Client - PKCE)
      Parameter Required Description
      response_type Yes Set the value to code to initiate the authorization code flow.
      client_id Yes The unique identifier for your client application.

      Format: YOUR_CLIENT_ID
      redirect_uri Yes The URI to which ServiceNow sends the authorization code.

      Example: https://yourapp.com/callback
      code_challenge Yes A base64url-encoded SHA-256 hash of the code verifier. This is used as part of the PKCE flow.
      code_challenge_method Yes Specifies the transformation method used for the code challenge. Set to S256.
      scope Optional A space-delimited list of requested scopes.

      Example: incident_read incident_write.
      state Yes A client-generated value used to avoid CSRF attacks. The value is returned unchanged in the redirect URI, enabling the client to validate it.
      Note:
      Starting with the Madrid release, the system property glide.oauth.state.parameter.required mandates the use of the state parameter in the OAuth requests. The state property is set to true by default in the new instances, and optional in upgraded instances. In case of missing state parameter, the authorization request fails and the following error is displayed: Missing State parameter in request.
      Private Clients

      Private clients (Example: Server-side applications) can securely store a client secret and do not require PKCE.

      • The authorization request is initiated by redirecting the user to the authorization endpoint. No client secret or PKCE code challenge is required in this step.
      • During the token request, the client includes the client secret along with the authorization code to obtain the access token.
      Perform a GET request to the authorization endpoint with the following parameters:
      Method: GET
Endpoint: https://<servicenow_base_url>/oauth_auth.do
      Table 2. Authorization Request Parameters (Private Client-Client Secret)
      Parameter Required Description
      response_type Yes Set the value to code to initiate the authorization code flow.
      client_id Yes The unique identifier for your client application.

      Format: YOUR_CLIENT_ID
      redirect_uri Yes The URI to which ServiceNow sends the authorization code.

      Example: https://yourapp.com/callback
      scope Optional A space-delimited list of requested scopes.

      Example: incident_read incident_write.
      state Yes A client-generated value used to avoid Cross-Site Request Forgery (CSRF) attacks. The value is returned unchanged in the redirect URI, enabling the client to validate it.
    3. Log in and grant access consent to the client application.
      Log in to ServiceNow (or IdP, if SSO is enabled), and grant access consent to the client application.
    4. ServiceNow (or IdP, if SSO is enabled) validates the credentials and ServiceNow returns an authorization code to the client.
      After the successful authentication, the browser is redirected to the redirect_uri, and the authorization code is included in the query string:
      https://yourapp.com/callback?code=AUTH_CODE&state=xyz123
    5. Initiate the authorization request.

      The client redirects the user to the ServiceNow authorization endpoint for an access token. The method of initiating the authorization request depends on the type of client: Public or Private.

      Public Clients

      Public clients (Example: Mobile or Single-page applications) cannot securely store a client secret. Therefore, they must use Proof Key for Code Exchange (PKCE) to enhance security.

      • In the authorization request, include the PKCE code challenge and specify the code challenge method.
      • During the token request, the client must send the code verifier to validate the authorization code.
      The client sends a POST request to token endpoint with the following parameters:
      
Method: POST  
Endpoint: https://<servicenow_base_url>/oauth_token.do  
Headers: Content-Type: application/x-www-form-urlencoded
      Table 3. Token Request Parameters (Public Client-PKCE)
      Parameter Required Description
      grant_type Yes Set the value to authorization_code to exchange the code for a token.
      code Yes The authorization code received from the authorization endpoint.
      redirect_uri Yes The URI used in the initial authorization request.

      Example: https://yourapp.com/callback
      client_id Yes The unique identifier for your client application.
      code_verifier Yes The original string used to generate the PKCE code_challenge.
      state Yes A client-generated value used to help prevent CSRF attacks. The value is returned unchanged in the redirect URI, enabling the client to validate it.
      Private Clients

      Private clients (Example: Server-side applications) can securely store a client secret and do not require PKCE.

      • The authorization request is initiated by redirecting the user to the authorization endpoint. No client secret or PKCE code challenge is required in this step.
      • During the token request, the client includes the client secret along with the authorization code to obtain the access token.
      Perform a POST request to the authorization endpoint with the following parameters:
      
Method: POST 
Endpoint: https://<servicenow_base_url>/oauth_token.do   
Headers: Content-Type: application/x-www-form-urlencoded
      Table 4. Token Request Parameters (Private Client-Client Secret)
      Parameter Required Description
      grant_type Yes Set the value to authorization_code to exchange the code for a token.
      code Yes The authorization code received from the authorization endpoint.
      redirect_uri Yes The URI used in the initial authorization request.

      Example: https://yourapp.com/callback
      client_id Yes The unique identifier for your client application.
      client_secret Yes The client’s secret used to authenticate with the token endpoint.
      state Yes A client-generated value used to help prevent CSRF attacks. The value is returned unchanged in the redirect URI, enabling the client to validate it.
    6. Access the ServiceNow APIs with the access token.
      Example:
      Make a GET request to the APIs using the access token. Include the access token in the Authorization header.
      Method: GET
End Point: https://<servicenow_base_url>/api/now/incident  
Authorization: Bearer YOUR_ACCESS_TOKEN
    7. Renew the access token if it has expired.
      Make a POST request to refresh the access token (private clients only) with the following parameters:
      
Method: POST  
Endpoint: https://<servicenow_base_url>/oauth_token.do  
Headers: Content-Type: application/x-www-form-urlencoded
      Table 5. Refresh Token Request Parameters (Private Client)
      Parameter Required Description
      grant_type Yes Set the value to refresh_token to request a new access token.
      refresh_token Yes The refresh token previously issued by the token endpoint.
      client_id Yes The unique identifier for your client application.
      client_secret Yes The client secret used to authenticate with the token endpoint.