OAuth Client Credentials Grant

Prerequisites

Role on the setup user: oauth_admin, mi_admin, or admin.

ServiceNow-side setup

1. Navigate to: *Machine Identity Console > Inbound integrations > New integration > OAuth Client credential grant*.

2. Fill the Details form:

• Name — your OAuth entity name.
• Provider Name — e.g., CLI Automation.
• Client ID — a unique identifier (you can specify or let the system generate one).
• Client Secret — the shared secret; store it securely.
• Active — true.

3. Optional: fill Auth Scope to restrict which APIs the client can access.

4. Optional: fill Advanced options — token format (JWT or Opaque) and token lifespan (default 1800 seconds).

5. Save.

6. View the created integration at *All > Inbound integrations > Application Registries*.

Register with sn

sn instance add default \
  --url your-instance.service-now.com \
  --auth-type oauth-client-credentials \
  --client-id YOUR_CLIENT_ID \
  --client-secret - \
  --token-endpoint https://your-instance.service-now.com/oauth_token.do \
  --default
# --client-secret - reads the secret from stdin

Optional: --scope <s> to narrow the token's authorization scope.

On first request, the CLI exchanges the client credentials for a Bearer token at the token endpoint and caches it at ~/.sn-skills/oauth-cache.json (mode 0600) with a 60-second safety margin before declared expiry. Subsequent requests reuse the cached token until it expires or the instance returns 401, at which point the cache entry is invalidated and the token is refetched.