REST API scope troubleshooting

  • Release version: Zurich
  • Updated July 31, 2025
  • 3 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 REST API scope troubleshooting

    This guide provides troubleshooting steps and answers common questions related to the REST API scope in ServiceNow, specifically focusing on authentication and authorization issues encountered during API setup and runtime.

    Show full answer Show less

    Troubleshooting actions

    • No auth scope check at runtime despite linking REST API with auth scope:
      • Ensure the sysapiaccesspolicy record is active, as inactive records are ignored at runtime.
      • Verify the system property com.glide.rest.api.auth.scope.check.enable is not set to false.
      • Confirm the OAuth token includes the useraccount auth scope.
    • Access token with different auth scope can access REST API:
      • Check that the relevant sysapiaccesspolicy record is active.
      • Review for other records applying to the same API but with different methods, versions, or resources that might grant access.
    • No auth scope check for BasicAuth and mutualAuth: This is expected because auth scope checks only apply to OAuth and OIDC tokens, not BasicAuth, Session Cookie, or Certificate-based authentication.
    • REST API call returns 403 with OAuth token: Look for the error "Missing required api access scope" indicating the auth scope check failed for that API.
    • Restoring deleted pre-defined useraccount: Export the useraccount XML from another instance and import it, or create a new useraccount and update the system property glide.oauth.token.scope.useraccount to point to the new record's sysid.

    Frequently asked questions

    • Can one OAuth token link to multiple auth scopes? Yes, an OAuth entity can have multiple auth scopes, and all tokens issued by it inherit these scopes.
    • Can different OAuth tokens with different auth scopes access the same REST API? Yes, access is granted if any one auth scope matches the REST API policy.
    • Does the useraccount auth scope grant full access? Yes, OAuth tokens with useraccount auth scope have full access.
    • Can OAuth token auth scopes change dynamically? Yes, auth scopes are retrieved from the linked OAuth entity at runtime, not hard-coded per token.
    • Do auth scopes persist after token refresh? Yes, they remain the same unless modified by an admin on the OAuth entity.
    • Can a new auth scope named 'useraccount' replace a deleted one? No, because runtime checks use sysid. Instead, update the system property glide.oauth.token.scope.useraccount to the new sysid.
    • If an admin modifies auth scopes on an OAuth entity, do existing tokens change? Yes, since auth scopes are referenced at runtime from the OAuth entity.
    • Can different tokens from the same OAuth entity have different auth scopes? No, all tokens share the same auth scopes assigned to their OAuth entity.
    • Can different auth scopes be defined per REST API endpoint? No, there is a unique constraint per endpoint, though multiple auth scopes may match the same endpoint.
    • Is auth scope check applied to BasicAuth? No, it only applies to OAuth and OIDC tokens.

    Troubleshooting actions can help resolve common issues when setting up or running the REST API scope.

    Table 1. Troubleshooting
    Issue Action
    REST API is linked with auth scope, however in runtime there is no auth scope check even using Bearer token authentication.
    • Make sure the sys_api_access_policy record is active. Runtime ignores inactive records.
    • Check if property com.glide.rest.api.auth.scope.check.enable is set to false.
    • Check if the OAuth token has useraccount auth scope.
    REST API is linked with auth_scope1, however the access token which has auth_scope2 is also able to access it.
    • Check if this record is active.
    • Check for this REST, check if any other records, which have the same APIs but different apply methods, versions, or resource.
    REST API is linked with auth scope, however in runtime there is no auth scope check for basicAuth and mutualAuth. It is expected since the REST API auth scope only applies to the OAuth access token or OIDC token. It doesn’t apply BasicAuth, Session Cookie and Certificate based authentication.
    REST API call return 403 when using the OAuth access token. Check for the error message "Missing required api access scope". If found then the auth scope check fails for this REST API
    Pre-defined useraccount is deleted and not sure to restore. Export useraccount as xml from the other instance and import it or create an useraccount and modify system property glide.oauth.token.scope.useraccount to the newly created sys_id record.

    Frequently asked questions

    Following are some of the frequently asked question when using the REST API Auth scope:

    Can one OAuth token be linked with several auth scopes?
    Yes, one oauth_entity can be linked with multiple auth scopes, every OAuth token issued by this oauth_entity has the same auth scopes.
    Can different OAuth tokens with different auth scopes access the same REST API?
    Yes, for the same REST API, it may be accessed by different auth scopes. As long as one auth scope is matched, the auth scope returns the results.
    Can OAuth access token with useraccount auth scope access any REST APIs?
    Yes, the useraccount has full access to auth scope.
    Can OAuth access token OAuth scope be changed dynamically?
    Yes, the auth scoped is not hard-coded with the access token in the oauth_credential table. Instead auth scope is getting from linked oauth_entity during runtime.
    Can OAuth token keep same auth scopes after refresh?
    Yes, auth scope will not change after token refresh, unless oauth_admin modify auth scope linked with oauth_entity.
    Pre-defined useraccount auth scope record is deleted, can a new auth scope with name useraccount be created?
    Creating a new auth scope with the same useraccount doesn't work. In the runtime, it uses the sys_id instead of name to do the auth scope check, modify the system property glide.oauth.token.scope.useraccount to the newly created sys_id record.
    If admin modify auth scoped linked with oauth_entity, are all the existing OAuth access token issued by this OAuth entity changed also?
    Yes, the auth scope is not directly linked with the OAuth access token, it is getting from oauth_entity during runtime.
    Can different OAuth access tokens issued by the same oauth_entity have different auth scopes?
    No, all access to the token is issued by the same oauth_entity and always have the same auth scopes.
    Can a user define different auth scopes for a particular endpoint?
    No, there is a unique constrain check for a particular REST API endpoint. However for the same REST API endpoint, it may have more than one matched auth scopes.
    Is the auth scope check used for BasicAuth also?
    No, auth scope check is only OAuth access token and OIDC token, it is not applied for basicAuth and mutualAuth