sndev.io / docs

REST API Key

ServiceNow REST API Key authentication — instance-side setup and CLI registration.

Not recommended for sn as a general auth method. The CLI writes to many tables across skills — business rules, script includes, ATF tests, catalog items, flows, instance-scan checks, and more. A REST API Key is narrow by design: it's most useful when you pair it with an Auth Scope that locks it to a specific REST API surface. Using an API Key without scoping (or scoping it to everything) gives up the security benefit without gaining the convenience of Basic Auth or OAuth. For CI and shared automation, prefer OAuth Client Credentials. For local development, Basic Auth against a PDI is simplest.

Prerequisites

  • Plugin activated: *API Key and HMAC Authentication* (com.glide.tokenbased_auth).
  • Roles on the setup user: api_service_admin, adaptive_auth_policy_admin.

Step 1 — Create an Inbound Authentication Profile

Navigate to: *All > System Web Services > API Access Policies > Inbound Authentication Profiles*.

Select New. Choose Create API Key authentication profiles.

Fill:

  • Name — a label for this profile (e.g., CLI Automation - API Key).
  • Application — the scope this profile applies to.
  • Auth Parameter — x-sn-apikey: Auth Header is the default.

Submit.

Step 2 — Create a REST API Key

Navigate to: *All > System Web Services > API Access Policies > REST API Key*.

Select New. Fill:

  • Name — label for the key.
  • Description — optional but recommended.
  • Active — true.
  • User — the ServiceNow user this key authenticates as.
  • Auth Scope — optional; restrict to specific APIs.
  • Expiry — optional; leave empty for no expiration.

Submit. Open the created record to view the Token value — copy it now. This is the API key you will pass to sn instance add.

Step 3 — Create a REST API Access Policy

Navigate to: *All > System Web Services > REST API Access Policies*.

Select New. Fill:

  • Name — a label.
  • Active — true.
  • REST API — the API to protect (e.g., Attachment API).
  • Other fields auto-populate.
  • Add the Authentication Profile from Step 1 to the Authentication Profiles related list.

Submit.

Register with sn

sn instance add default \
  --url your-instance.service-now.com \
  --auth-type api-key \
  --token - \
  --default
# --token - reads the API key token from stdin

Optional flags:

  • --user <name> — informational (records the SN user the key represents; not used for authentication).
  • --api-key-header <name> — override the default x-sn-apikey header when your inbound auth profile is configured to read the token from a different header.

Every subsequent sn command against this target injects x-sn-apikey: <token> into the request headers. No password stored on disk.