OAuth 2.0 Provider setup
Before configuring any OAuth flow for inbound access, navigate to System OAuth > Application Registry and create an OAuth provider record. This is where the client_id and client_secret are generated. Each external application that will authenticate against ServiceNow needs its own Application Registry record.
Grant Type 1: Client Credentials (most common for server-to-server)
Use when a server or service needs to call ServiceNow APIs without a user context. No browser redirect, no user login. The calling application authenticates as itself using its client credentials.
POST /oauth_token.do
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&client_id=[your_client_id]
&client_secret=[your_client_secret]
&username=[integration_user]
&password=[integration_user_password]
// Response:
{ "access_token": "abc123...", "expires_in": 1800, "token_type": "Bearer" }
// Use the token:
GET /api/now/table/incident
Authorization: Bearer abc123...The access token expires (default 30 minutes). Cache it and reuse until expiry, then request a new one. See the Table API reference for using the token with ServiceNow APIs.
Grant Type 2: Authorization Code (user-delegated access)
Use when a third-party application needs to act on behalf of a specific ServiceNow user — the user must explicitly authorise the access.
// Step 1: Redirect user to
GET /oauth_auth.do?response_type=code&client_id=[id]&redirect_uri=[uri]
// User logs in and authorises
// Step 2: Receive auth code at redirect_uri
?code=[auth_code]
// Step 3: Exchange code for tokens
POST /oauth_token.do
grant_type=authorization_code&code=[auth_code]
&client_id=[id]&client_secret=[secret]&redirect_uri=[uri]
// Response includes access_token AND refresh_tokenGrant Type 3: Resource Owner Password Credentials
Sends user credentials directly to get a token. Not recommended for new integrations — use Client Credentials instead. Only appropriate for migrating legacy integrations that currently use username/password HTTP Basic Auth.
Grant Type 4: JWT Bearer Token
For calling ServiceNow from systems that already issue JWTs (Okta, Azure AD, Ping Identity). ServiceNow validates the JWT signature against a configured public key — no password exchange needed.
Setup: configure a JWT Provider in System OAuth > JWT Providers with the issuer, audience claim, and signing key.
Token refresh
Authorization Code grants return a refresh_token that lets you get new access tokens without re-authenticating the user:
POST /oauth_token.do
grant_type=refresh_token
&refresh_token=[refresh_token]
&client_id=[id]
&client_secret=[secret]Outbound OAuth — ServiceNow calling external APIs
For ServiceNow calling OAuth-protected external APIs: configure an OAuth Profile at System OAuth > OAuth Profiles and reference it via a Connection Alias. Flow Designer and REST Messages can then use the profile for automatic token management.
Related: RESTMessageV2 · Credential Aliases · Table API
OAuth 2.0 flow types in ServiceNow
ServiceNow supports two OAuth 2.0 flows for inbound authentication. The Authorization Code flow is the standard browser-based flow: the user is redirected to ServiceNow's OAuth login, approves the access request, and receives an authorization code that is exchanged for an access token. Use this when a human is authenticating. The Client Credentials flow is machine-to-machine: the calling system presents a client ID and secret directly for a token, with no human interaction. Use this for server-to-server integrations, scheduled processes, and any scenario where no human is present.
Configuring an OAuth provider (for outbound calls)
When ServiceNow needs to call an external API that requires OAuth, configure an OAuth Provider record: navigate to System OAuth > Application Registry, create a new OAuth API Authentication. Provide the token URL, client ID, and client secret from the external system. Store the secret in the record — ServiceNow encrypts it at rest. Reference the OAuth provider record in your Connection and Credential Alias rather than passing credentials directly in RESTMessageV2 calls. This separation means credential rotation is done in one place (the alias record) rather than in every script that uses the integration. See our guide on triggering a Flow from an external system.
OAuth token lifecycle management
OAuth access tokens expire — typically after 1 hour, though this depends on the provider. ServiceNow handles token refresh automatically when you use the OAuth framework correctly — the RESTMessageV2 OAuth configuration handles refresh token exchange when the access token expires. If you are seeing 401 errors on long-running integrations, check whether the token refresh is configured and whether the refresh token itself has expired (refresh tokens have a longer lifetime, typically 24 hours to 30 days).
// Check OAuth token status (Scripts - Background)
var tokenRecord = new GlideRecord('oauth_credential');
tokenRecord.addQuery('credential_id', YOUR_OAUTH_PROFILE_SYS_ID);
tokenRecord.query();
if (tokenRecord.next()) {
gs.log('Token expires: ' + tokenRecord.getValue('expires_on'));
gs.log('Refresh token: ' + (tokenRecord.getValue('refresh_token') ? 'present' : 'missing'));
}Related: RESTMessageV2 guide · Credential Aliases · HTTP status codes · REST API overview
OAuth 2.0 for inbound API access to ServiceNow
When external systems need to call ServiceNow's REST APIs using OAuth, configure an OAuth Application record in ServiceNow: navigate to System OAuth > Application Registry > New > Create an OAuth API endpoint for external clients. Configure the client ID (auto-generated or custom), client secret, token expiry, and refresh token expiry. The external system uses the client ID and secret to obtain tokens from ServiceNow's token endpoint: https://[instance].service-now.com/oauth_token.do.
// Token request from external system (Client Credentials flow)
POST https://[instance].service-now.com/oauth_token.do
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
// Response
{
"access_token": "eyJ...",
"token_type": "Bearer",
"expires_in": 1800,
"refresh_token": "eyJ...",
"scope": "useraccount"
}The access token is then passed as a Bearer token on subsequent API calls: Authorization: Bearer eyJ.... Each call to the ServiceNow Table API or Scripted REST API with a valid Bearer token authenticates as the OAuth Application's associated user account. Configure that account with only the roles needed for the integration — the principle of least privilege applies here as it does everywhere in the security architecture.
OAuth security best practices
Several practices reduce OAuth-related security risk in ServiceNow integrations. Use a dedicated integration user for each integration — do not share OAuth credentials between different external systems. Each system should have its own client ID and secret with only the roles needed for its specific operations. Rotate client secrets regularly (quarterly or when staff with access to credentials leave). Set appropriate token expiry times — 30 minutes to 2 hours for access tokens, 24 hours to 7 days for refresh tokens, depending on your security requirements. Use the Client Credentials flow for server-to-server integrations and the Authorization Code flow only when a human user is authenticating. Audit OAuth token usage through the System Log periodically — look for unusual call volumes, calls at unexpected hours, or calls to unusual API endpoints that might indicate a compromised token.
Debugging OAuth failures systematically
OAuth failures in ServiceNow integrations typically manifest as 401 responses on API calls. Debug in sequence: verify the OAuth Application record is active and the client ID/secret match exactly what the external system is using (copy-paste, do not retype — a single character difference causes 401s with no useful error message). Check the token expiry — if calling from a long-running process, verify the token is being refreshed before expiry. Review the System Log filtered by source "OAuth" for any token issuance or validation errors. Test token issuance independently using curl or Postman before diagnosing the integration code — confirming that OAuth works in isolation eliminates half the possible failure points before looking at the application layer.
OAuth vs basic auth — when to use each
Basic Authentication (username:password in Base64) is appropriate for development, testing, and low-risk internal integrations where the data is not sensitive and the credentials are for a service account with limited access. It should never be used for integrations that access sensitive data, integrations accessible from the internet, or integrations that run in customer-facing contexts. OAuth 2.0 is the correct choice for any integration that needs to be production-grade, particularly when: the integration accesses sensitive records, the integration will run for a long time (OAuth refresh tokens handle credential rotation more gracefully than updating stored passwords), or the integration needs to authenticate as specific users rather than a generic service account (OAuth Authorization Code flow). The extra setup time for OAuth is worth it in any scenario where security and maintainability matter.
Connection Aliases — managing OAuth at scale
Connection and Credential Aliases are the recommended way to manage OAuth credentials in ServiceNow integrations. Rather than configuring OAuth tokens directly in RESTMessageV2 records or scripts, create a Connection Alias that references the OAuth profile. Use the alias in all integration records. When credentials change (client secret rotation, new OAuth profile), update the alias record once rather than updating every integration that uses those credentials. This is especially important in multi-environment setups where development, test, and production instances use different OAuth profiles for the same external system — the alias name can be the same across environments while pointing to environment-specific credentials.
OAuth 2.0 is the foundation of secure ServiceNow integrations. Combined with Connection and Credential Aliases for credential management, RESTMessageV2 for the API calls, and proper status code handling for resilience, you have a complete production-grade integration pattern that handles authentication, execution, and error recovery correctly.
ServiceNow provides detailed OAuth 2.0 documentation in the official product documentation (docs.servicenow.com) under "Integrate > Security and authentication > OAuth 2.0." The documentation covers both inbound OAuth (external systems authenticating to ServiceNow) and outbound OAuth (ServiceNow authenticating to external systems) with step-by-step configuration guides for both flows. Use the official documentation alongside this guide when setting up a specific OAuth integration for the first time — the product documentation includes release-specific screenshots and configuration paths that this guide does not replicate.
OAuth implementation quality is often invisible until something breaks — a token expiry causes an integration to stop working at 2am, a rotated secret that was not updated in all the right places causes a cascading integration failure. The patterns described in this guide — Connection Aliases for centralised credential management, systematic error handling for 401 responses, regular secret rotation — are specifically designed to make the invisible problems visible before they become incidents. Implement them from the start rather than retrofitting them after your first OAuth-related outage.