Join the #BuildWithBuildAgent Challenge! Get recognized, earn exclusive swag, and inspire the ServiceNow Community with what you can build using Build Agent.  Join the Challenge.

Handling Non-Standard Token-Based Integrations in ServiceNow

Chaitra Geetha
ServiceNow Employee
ServiceNow Employee
3 weeks ago

Overview

Many enterprise systems expose APIs that require authentication tokens, but not all of them follow the standard OAuth 2.0 grant flows. In some cases, the token must be retrieved by posting a payload containing a username and password to a custom endpoint, and the response provides an access_token, refresh_token, and expires_in field. This is similar to OAuth, but not the same, since it doesn’t use any of the recognized grant types like client credentials or authorization code.

This document provides a generic, reusable guideline for implementing such integrations securely in ServiceNow, based on real implementation experience and customer workshops.

🧩 Common Problem

Customers often end up making a token request for every single API call — sending the username and password repeatedly to get a new access token. This creates unnecessary latency and major security concerns. Ideally, credentials should only be used once to get the initial access and refresh tokens, and thereafter the system should automatically use the refresh token to renew the access token when it expires.

Since this is not a standard OAuth flow, the question is: where do we store and manage these tokens securely in ServiceNow without building custom tables?

 

💡 Recommended Solution Architecture

Instead of creating a custom storage mechanism, leverage ServiceNow’s existing Application Registry → OAuth Entity Profile → OAuth Requester Profile hierarchy. These tables are automatically created and managed by the platform and can be adapted to store and refresh tokens even for non-OAuth flows.

This approach was validated through a real implementation discussion (AWS Cognito example), where we configured ServiceNow to store and manage tokens in an out-of-the-box manner while still handling a custom authentication flow.

🧭 Step-by-Step Guideline

 

1️⃣ Create an Application Registry

Navigate to System OAuth → Application Registry and create a new OAuth 2.0 record. Even if your API provider doesn’t support standard OAuth, this record will serve as the container for your token management.

 

2️⃣ Verify the OAuth Entity Profile

Saving the Application Registry automatically generates an OAuth Entity Profile that links to this application. You can access it directly via:
oauth_entity_profile.list

 

3️⃣ Create a Requester Profile

The OAuth Requester Profile table (oauth_requestor_profile) is not visible in the left navigation pane. Open it manually using:
oauth_requestor_profile.list

Create a new record in this table with the following field values:

  • OAuth Entity Profile → select the Entity Profile created in Step 2

  • Requestor ID → sys_id of the Application Registry created in Step 1

This record links the Application Registry and Entity Profile, establishing the context under which tokens will be stored and retrieved.

 

4️⃣ Persist Tokens in OAuth Credential (Manual Insert for Non-Standard Flows)

When the token exchange is custom and not handled automatically, insert two records into oauth_credential using GlideRecord — one for the access token and another for the refresh token.

Required fields to populate:

  • Token received — the actual token value returned by the provider

  • OAuth requester profile — sys_id of the Requester Profile

  • Peer — sys_id of the Application Registry

  • Expires — token validity period (in seconds)

  • Name — a descriptive name (for example, IntegrationName – Access Token)

  • Type — specify access_token or refresh_token

The peer and oauth_requester_profile fields are critical to bind the token to the correct OAuth context.

Example insert (conceptual):

// access token
var acc = new GlideRecord('oauth_credential');
acc.initialize();
acc.type = 'access_token';
acc.name = 'IntegrationName - Access Token';
acc.token_received = res.access_token;
acc.expires = res.expires_in;
acc.peer = appRegSysId;                 // Application Registry sys_id
acc.oauth_requester_profile = reqProfSysId; // Requester Profile sys_id
acc.insert();

// refresh token
var ref = new GlideRecord('oauth_credential');
ref.initialize();
ref.type = 'refresh_token';
ref.name = 'IntegrationName - Refresh Token';
ref.token_received = res.refresh_token;
ref.peer = appRegSysId;
ref.oauth_requester_profile = reqProfSysId;
ref.insert();

 

5️⃣ Retrieve & Use Tokens via OOTB API

Use ServiceNow’s OAuth client to fetch the active token (and refresh as needed) and then call your downstream API.

// Retrieve token bound to Entity + Requester profiles
var token = new sn_auth.GlideOAuthClientRequest().getToken(appRegEntitySysId, reqProfSysId);
var access = token.getAccessToken();
var refresh = token.getRefreshToken();
var expiry = token.getExpiresIn(); // 0 means expired

API reference: GlideOAuthClient — see platform docs for details on token retrieval/refresh.

⚙️ Real Implementation Example (AWS Cognito)

In a customer workshop, we followed the same steps using AWS Cognito as a test case. The setup included:

  • Creating an Application Registry for Cognito.

  • Manually creating a Requester Profile and linking it to the OAuth Entity Profile.

  • Writing a script to call the Cognito token endpoint, sending username and password to retrieve access and refresh tokens.

  • Storing tokens in oauth_credential — one for access and one for refresh — and associating both with the same Application Registry and Requester Profile sys_ids.

  • Using standard OAuth client methods like getAccessToken(), getRefreshToken(), and getExpiresIn() for token lifecycle handling.

This proved that ServiceNow’s out-of-the-box OAuth framework can handle even non-standard token exchanges securely and effectively.

✅ Key Guidelines for Implementation

  • 🔒 Do not create custom tables for token management. Use Application Registry and its related profiles.

  • 🧠 Use manual GlideRecord inserts if token exchange is fully custom.

  • 🔐 Store credentials in encrypted system properties.

  • 🔁 Use the refresh token to renew access tokens, avoiding repeated credential use.

  • 🧱 Link records correctly: Application Registry → OAuth Entity Profile → OAuth Requester Profile → OAuth Credential.

🎯 Conclusion

This method provides a reliable, secure, and fully OOTB-compatible pattern for handling non-standard token-based integrations in ServiceNow. It reuses existing platform features (Application Registry, OAuth Entity Profile, OAuth Requester Profile, and OAuth Credential) to maintain tokens securely, supports refresh mechanisms, and avoids repetitive authentication calls — delivering a scalable foundation for any custom API integration.

  • 303 Views