ServiceNow OAuth Profile Explained

What an OAuth Profile Is

An OAuth Profile in ServiceNow configures how external applications can request permission to access ServiceNow data on behalf of users. OAuth is a security protocol that lets users grant permissions without sharing passwords. For example, a third-party scheduling tool can request permission to access your ServiceNow calendar. The user approves the request, and the tool gets access only to the calendar, not to passwords or other sensitive data.

OAuth profiles protect security by avoiding the need to share passwords with third-party tools. They also enable fine-grained permissions: a tool might get permission to read incidents but not to create or modify them. If you revoke permission, the tool immediately loses access; the user does not need to change their password.

How OAuth Profiles Work

An OAuth profile defines what permissions an external application can request. The profile includes which data the application can access (incidents, change requests, users), what operations are allowed (read, create, modify), and which users or roles can grant permission. When a user authorizes the application, they see a permission request listing what the application wants access to. If they approve, the application receives an access token valid for a specific period.

The access token is used by the application to make API calls to ServiceNow on the user’s behalf. The application cannot use the token to exceed the permissions the user granted. If the application requests data the user did not authorize, the request is denied. This architecture prevents applications from trying to access data beyond their authorization.

A Worked Example

Your company uses a project management tool built by a third party. The tool wants to sync work items to ServiceNow tasks. You create an OAuth profile authorizing the tool to read and create tasks, but not to delete or modify existing tasks. The tool is authorized to see only tasks assigned to the user, not all tasks in the system.

When a user first uses the tool, they are prompted to authorize it. They see a permission request: “This application wants to create and read your tasks.” They approve. The tool receives an access token and can now access the user’s tasks through the ServiceNow API. The user can revoke access at any time, and the tool is immediately locked out.

Security and Permission Management

OAuth profiles let administrators control what external applications can do. You can revoke permissions for an application, disabling all users’ access immediately. You can limit applications to specific roles: an accounting system might access financial data only for accounting staff, not for all users. You can set token expiration: applications must re-request permission periodically.

Token Management and Refresh

Access tokens have expiration times configured in the OAuth profile. Tokens that expire require the application to request a new token, which typically happens transparently to users. Refresh tokens allow applications to get new access tokens without requiring users to re-authorize. This balance between security and user experience is configured per application: highly sensitive applications might require frequent re-authorization, while less sensitive applications can use longer-lived tokens.

Single Sign-On and OAuth

OAuth is related to but different from single sign-on. Single sign-on (SSO) lets users log in once to multiple systems using one identity. OAuth handles authorization: what data applications can access. Some systems use OAuth for SSO; others use different protocols. ServiceNow supports both OAuth and other authentication protocols for different scenarios.

API Authorization and Service Accounts

Applications connecting to ServiceNow through APIs need authorization. OAuth profiles can authorize service accounts: application-to-application connections where one application calls ServiceNow APIs on behalf of another. Service account authorization avoids storing user passwords in application configuration.

Scope limitation prevents service accounts from accessing more data than necessary. A backup application might have authorization to read incident records but not to modify them. A reporting tool might have authorization to read only specific fields relevant to reporting, not sensitive customer data.

Token Expiration and Renewal

OAuth tokens have limited lifetime. Short token lifetime (hours) is more secure; long token lifetime (days or weeks) is more convenient. When a token expires, the application must request a new one. ServiceNow handles token refresh automatically for well-behaved applications, but applications must be configured to refresh rather than fail when tokens expire.

Choosing the grant that matches how the integration really runs

An OAuth client in the platform can be set up for several kinds of access, and the choice has to follow the way the integration actually runs. When a person’s own session drives an action, such as a mobile app that lists the person’s own tasks, the token represents that person. When a background job runs overnight with no user present, the token has to represent a service identity, and a user-bound token will expire or fail the moment that person changes role. Mixing these two patterns in one client is a common design error. Ask, for each integration, who is the caller when nobody is watching, and let the answer decide the grant and the identity.

Integration pattern	Identity the token should carry	Symptom when the pattern is wrong
Interactive app used by a signed-in person	That person, limited to what they can already see	Users see other people’s data, or the app fails for anyone whose role differs from the builder’s
Scheduled batch job with no user present	A dedicated service identity with the narrowest role that works	The job stops when the account that created it is deactivated or changes role
Partner system pushing events	A service identity scoped to the event tables only	The partner gains read access to tables that have nothing to do with its events

Token lifetime is a trade-off you can describe to a reviewer

A short access token limits the damage from a leaked token, and a long one spares the integration from refreshing. Neither is correct in general. The question is what the integration does when a refresh fails. A job that refreshes every time it runs will recover from a short lifetime without any drama, while a job that holds one token for hours will fail halfway through a large sync and leave records in a partial state. Design the refresh behavior first, then choose the lifetime that the refresh behavior can survive, and write the decision where the integration’s owner can see it, as the integration monitoring guide covers.

Ordered setup that keeps the scope narrow

1. Write the list of operations the integration needs, in terms of tables and verbs, before creating any client. Scope follows that list, not the other way around.
2. Create the client in each environment separately, with its own client identifier and secret. A client copied from production into a test instance carries production trust.
3. Assign the service identity a role that covers only the tables on the list, and test that it cannot read an adjacent table.
4. Set the token lifetime after checking the refresh behavior of the integration against a deliberately expired token.
5. Store the client secret in a credential alias rather than in a script include, a property value or a shared document.
6. Record who approved the client, what it can reach and the date of the next review.

What breaks after go-live

Many OAuth failures in production are not dramatic. A token expires during a long run and the job logs a generic unauthorized error. A service identity is deactivated during a leaver process because someone assumed it was a person. A client secret is rotated in the platform but not in the external system, so every call fails until the mismatch is found. A new role is added to the service identity for a different project and quietly widens what the integration can read. Each of these is preventable with a short review: check the identity’s status against the leaver list, check the secret rotation against the vendor’s console, and compare the identity’s roles with the list of operations the integration needs.

When OAuth is more than the job needs

OAuth is built for delegated access across systems. A simple, single-purpose integration between two systems that both sit inside the same controlled network may be served by a service account with a credential alias and a narrow role, which is easier to explain. The extra moving parts of tokens, refresh and client registration earn their cost when a third party needs access, when access must be revoked for one party without affecting others, or when audit has to show which application made each call.

Questions to put to the integration owner

• Which identity does the integration use when nobody is logged in, and who owns that identity?
• What happens to a half-finished run if its token expires?
• Which tables does the client need, and which of its current roles are not on that list?
• How would this integration be revoked without disrupting the others?

Frequently asked questions about OAuth profiles

Can one OAuth client serve several integrations?

It can, but the audit trail then shows one caller for many purposes. If the integrations have different owners or different risk levels, give each its own client, even when they share a service identity.

Why does a token work in the test tool but fail in the job?

The test tool may use a different identity, a different grant or a token issued moments earlier. Compare the identity and the token age used by the failing job with those used by the test before changing the client.

Do we need to revoke tokens when someone leaves?

Revoke any token issued to that person’s session, and check whether any client was created or owned by them. The leaver process should cover both, because a client without an active owner tends to keep running long after its purpose has gone.

Is OAuth the same thing as single sign-on?

No. Single sign-on proves who a person is when they log in. OAuth decides what an application may do with that person’s access or with a service identity. The two often appear together, but a configuration fault in one does not tell you anything about the other.

Next step

If several integrations share one client or run under identities nobody can explain, review clients and identities together.

Related guides: ServiceNow Integrations.