Basic Auth (Quick Start)

Basic auth is the Quick Start path. It requires no instance-side plugin activation and works immediately on any ServiceNow instance. Use it for local development against a PDI or personal developer instance.

Basic auth stores credentials in ~/.sn-skills/instances.json. The file is created at mode 0600 (owner read/write only) inside a directory at 0700. On shared machines or CI environments, prefer a credential store or short-lived token approach instead.

Register your instance

sn instance add default \
  --url your-instance.service-now.com \
  --user admin \
  --pass - \
  --default
# --pass - reads from stdin — avoids exposing the password in ps(1) output

The --default flag sets this as the target instance for all commands that accept --target. You can register multiple instances and switch between them:

sn instance add dev --url dev12345.service-now.com --user admin --pass -
sn instance add test --url test67890.service-now.com --user admin --pass -
sn instance use dev   # set default
sn execute manifest.ts --target test  # override for one run

Verify connectivity

sn instance test default
# or
sn get sys_user sysparm_limit=1

When to switch: use OAuth Client Credentials for CI pipelines, team-shared automation, or any workflow where you don't want a human password stored on disk. See the auth-oauth page for instance-side setup and sn instance add --auth-type usage.

REST ATF steps need basic auth. The ATF REST-inbound step types (including sn-atf.wrap_rest_endpoint_test) authenticate via a sys_auth_profile_basic record — they do not work with API keys or OAuth. If your manifest exercises the ATF REST primitive, make sure the basic-auth profile it references has roles to hit the endpoints under test (e.g., itil for /api/now/table/incident, or a dedicated integration role for scripted REST APIs).