Authentication

Configure an API key, check your active identity and workspace, and manage named profiles for multiple workspaces or environments.

Signing in

Store a valid API key before running any command that calls the TestSprite API. The fastest path is testsprite setup, which prompts for the key, verifies it with the server, installs the agent skill into your repo, and prints a summary:

testsprite setup --agent AGENT

Replace AGENT with claude, cursor, cline, windsurf, antigravity, kiro, copilot or codex. For credentials only, use --no-agent. A rejected key never overwrites a working profile. See Installation for the full walkthrough.

TestSprite API key: ********
TestSprite initialized.

  profile:  default
  env:      production
  email:    [e-mail]
  scopes:   read:projects, read:tests, read:me, write:tests, run:tests, write:projects, read:schedules, write:schedules, run:tunnel

For CI and scripts, skip the prompt:

TESTSPRITE_API_KEY=sk-... testsprite setup --from-env --yes --no-agent

The CLI never accepts an API key as a flag or argument, since it would leak into shell history and process listings. Use the prompt, --from-env, or TESTSPRITE_API_KEY.

Checking who you are

testsprite auth status

userId: usr_1478d468
name:   Your Name
email:  [e-mail]
keyId:  key_a1b2c3d4
endpoint: https://api.testsprite.com
env:    production
scopes: read:projects, read:tests, read:me, write:tests, run:tests, write:projects, read:schedules, write:schedules, run:tunnel
org:    Checkout Team (Standard, member)
routing: v3
orgs: My workspace (org_5c1e…, personal, role: owner); Checkout Team (org_9a7d…, role: member)
org binding: Checkout Team (org_9a7d…, role: member)

The org: line is the workspace the key acts in, with its plan and your role there; orgs: lists every workspace you belong to. While that workspace is paused, a workspace: line says so and links to billing. If the key lacks write:tests or run:tests, a note: line lists the gap. Add --output json for machine-readable output.

Signing out

testsprite auth remove

This deletes the active profile’s entry from ~/.testsprite/credentials; other profiles are untouched.

Profiles

Credentials live in ~/.testsprite/credentials (an INI file, mode 0600). Each section is a named profile. Because a key acts in one workspace, a profile per workspace is how you work across several; profiles also keep an interactive key apart from a CI key:

[default]
api_key = sk-...

[ci]
api_key = sk-...

testsprite --profile ci setup --no-agent   # create or update the profile
testsprite --profile ci project list       # use it
export TESTSPRITE_PROFILE=ci               # or for the whole session

A missing profile exits 5. Resolution order is --profile > TESTSPRITE_PROFILE > default for the profile, and TESTSPRITE_API_KEY > the profile’s file entry for the key. See Configuration.

Scopes

Keys carry scopes that gate commands. A key minted in the portal gets every scope below, narrowed to your role in its workspace: Owner, Admin, and Member keep them all, and a Viewer has none, so every command is refused. Check yours with auth status. Existing keys can already use --local.

Scope	Gates
read:me	auth status, usage
read:projects	project list, project get, project env list, project env get, project sign-in get
read:tests	test list, test get, test steps, test result, test code get, test failure get, test failure summary, test artifact get, test wait, testlist list, testlist get; also test run --local, which reads the test first
write:tests	test create, test create-batch, test update, test delete, test delete-batch, test code put, test plan put, test plan accept, testlist create, testlist update, testlist delete, testlist add, testlist remove
write:projects	project create, project update, project delete, project credential, project auto-auth, project env create, project env update, project env delete, project env set-default, project sign-in set, project docs, test plan generate
run:tests	test run, test rerun, test flaky, test cancel, testlist run
read:schedules	schedule list, schedule get, schedule run list
write:schedules	schedule create, schedule update, schedule delete
run:tunnel	test run --local, any run that opens an automatic tunnel, tunnel start, tunnel list, tunnel status, tunnel stop

agent install is local-only and needs no scope; setup works with any valid key.

A scope error prints the required and granted scopes. The portal has no scope picker, so a key holds every scope your role allows. An empty granted list means your role in that workspace is Viewer: ask an Admin or the Owner to make you a Member.

Keys and workspaces

A key acts in the workspace it was minted in. Switch to that workspace in the portal and mint the key under Workspace Settings → Connections → API Keys: everything the CLI creates with it belongs to that workspace and draws on its balance, and auth status names it on the org: line. To work in another workspace, mint a key there and store it as a separate profile.

Keys need the Member role or above, and stop working when you leave or are removed from the workspace. None can be minted while the workspace is paused. You can hold 2 active keys per workspace, so revoke one before replacing a lost key at the cap. Keys starting with sk-user- predate workspace keys; they keep working and always act in your default workspace. See API Keys.

Where to Go Next

Projects

Create and manage projects

CI/CD Integration

Non-interactive auth for pipelines