OAuth API request parameters

  • Release version: Yokohama
  • Updated January 30, 2025
  • 2 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of OAuth API request parameters

    This content explains the parameters used in ServiceNow's OAuth API access token requests, focusing on how clients request and refresh access tokens securely. It highlights the required parameters for different grant types and important considerations on content type and security.

    Show full answer Show less

    Key Features

    • Content-Type Requirement: OAuth API requests must use application/x-www-form-urlencoded content type. Using application/json results in errors.
    • Required Request Parameters:
      • granttype: Specifies the authorization method. Valid values are password (using user credentials) or refreshtoken (using an existing refresh token).
      • clientid: Unique ID auto-generated for the client application requesting the token.
      • clientsecret: Shared secret string for authorizing communication between the instance and OAuth client.
    • Parameters for Password Grant Type: Requires username and password to authenticate the user.
    • Parameters for Refresh Token Grant Type: Requires an existing refreshtoken to obtain a new access token.
    • User Credential Requests: When authorizing with user credentials, both an access token and a refresh token are returned. The instance verifies user status and session activity before issuing tokens.
    • Refresh Token Requests: Requests using a refresh token return only a new access token, provided the refresh token is valid and unexpired. This method is considered more secure than transmitting user credentials repeatedly.

    Practical Application

    ServiceNow customers should ensure their OAuth token requests adhere to the required content type and parameters based on the grant type in use. For initial authorization or obtaining new refresh tokens, use user credentials with the password grant type. For subsequent token renewals, use the refreshtoken grant type to reduce transmission of sensitive user credentials. Properly managing these parameters enables secure, efficient OAuth token handling within ServiceNow integrations.

    Learn about the OAuth API request parameters that access token requests use.

    Note:
    The content-type of the OAuth API should be application/x-www-form-urlencoded. A content-type of application/json results in an unspecified error.
    Table 1. Access token request parameters
    Request parameter Description
    grant_type [Required] The type of credentials authorizing the request for an access token. This parameter must have one of the following values:
    • password: A set of user credentials to authorize the access token request. Specify the user credentials in the username and password parameters.
    • refresh_token: An existing refresh token authorizes the access token request. Specify the refresh token in the refresh_token parameter.
    client_id [Required] Auto-generated unique ID of the client application requesting the access token.
    client_secret [Required] Shared secret string that the instance and the OAuth application use to authorize communications with one another.
    username User account name that authorizes the access token request. This parameter is required for access token requests with a grant_type of password.
    password Password for the user account that authorizes the access token request. This parameter is required for access token requests with a grant_type of password.
    refresh_token Existing refresh token that authorizes the access token request. This parameter is required for access token requests with a grant_type of refresh_token.

    Requests Using User Credentials

    The instance requires clients to provide user login credentials when first authorizing the client or when authorizing the creation of a new refresh token. This type of request always returns two tokens:

    • An access token
    • A refresh token

    The instance verifies that the user is active, not currently locked out, and has an interactive session. If any of these conditions are false, the instance does not produce an access token. Access requests made within the expiration time of the access token always return the current access token.

    Note:
    This type of authorization grant relies on TLS encryption to protect the user credentials during transmission.

    The following example illustrates requesting an access token with a set of user credentials (Spaces have been added to improve readability).

    
$ curl -d"grant_type=password&client_id=be3aeb583ace210011c15b24a43e25d8
&client_secret=client_password
&username=admin&password=admin" 
https://instancename.service-now.com/oauth_token.do

    Requests Using a Refresh Token

    The instance can use an existing refresh token to create a new access token. This type of request returns only an access token. The instance confirms that the refresh token has not expired before generating a new access token. Access requests made within the refresh token expiration time always return the current refresh token. Transmitting refresh tokens is generally more secure than transmitting user credentials. The following example illustrates requesting an access token with an existing refresh token (Spaces have been added to improve readability).

    
$ curl -d"grant_type=refresh_token&client_id=be3aeb583ace210011c15b24a43e25d8
&client_secret=client_password
&refresh_token=w599voG89897rGVDmdp12WA681r9E5948c1CJTPi8g4HGc4NWaz62k6k1K0FMxHW40H8yOO3Hoe" 
https://instancename.service-now.com/oauth_token.do