Authentication

Use staplehire login for local development, or set STAPLEHIRE_KEY for agents, scripts, and CI. Every command authenticates the same way: by resolving an API key.

staplehire login
staplehire whoami

Log in with your browser

staplehire login runs a secure PKCE OAuth flow:

A local callback server starts

The CLI opens a loopback server on 127.0.0.1 and your default browser to app.staplehire.com. Log in or create an account if needed.

You authorize CLI access

Approve the hire:write scope for “Staplehire CLI”. The browser redirects back to the local callback with an authorization code.

The key is exchanged and saved

The CLI exchanges the code (plus the PKCE verifier) with the API gateway, then writes STAPLEHIRE_KEY to a .env file in your current directory and adds .env to .gitignore if one exists.

staplehire login

✓ Authenticated as Acme Corp
✓ Wrote STAPLEHIRE_KEY to /path/to/project/.env

staplehire login always authenticates against the production gateway and dashboard. Override with --app-url / --api-url (or STAPLEHIRE_APP_URL / STAPLEHIRE_API_URL) only when testing against a non-production environment.

Verify the active key and organization at any time:

staplehire whoami

{
  "user": { "id": "usr_…", "email": "you@company.com" },
  "organization": { "id": "org_…", "name": "Acme Corp" }
}

How the API key is resolved

The CLI looks for an API key in this order and uses the first one it finds:

Priority	Source	Example
1	`--api-key` flag	`staplehire --api-key sh_live_xxx roles list`
2	`STAPLEHIRE_KEY` environment variable	`export STAPLEHIRE_KEY=sh_live_xxx`
3	`.env` in the current directory	Written automatically by `staplehire login`

Keys are prefixed sh_live_… (production) or sh_test_… (test). staplehire doctor shows which source the active key came from:

staplehire doctor -q | jq '.checks[] | select(.name == "API Key")'

Never pass an API key as a literal command-line argument in shared shells, scripts committed to source control, or CI logs — it can leak into shell history and process listings. Prefer STAPLEHIRE_KEY from a secret store. staplehire login keeps your .env out of git automatically.

Use an API key for agents and CI

Browser login is for humans. Agents, scripts, and CI should set STAPLEHIRE_KEY directly. Create a key in Settings → Developers.

export STAPLEHIRE_KEY=sh_live_xxx
staplehire doctor -q
staplehire whoami | jq '.organization.id'

For a single command without exporting, use --api-key:

staplehire --api-key sh_live_xxx roles list

See Use in CI for a GitHub Actions example.

Log out

logout removes STAPLEHIRE_KEY from the .env in your current directory and clears it from the current process environment.

staplehire logout

{ "logged_out": true, "env_path": "/path/to/project/.env", "key_removed_from_env": true }

Common errors

Error	Exit code	Fix
`AuthenticationError` (401)	`2`	Run `staplehire login` or set a valid `STAPLEHIRE_KEY`
`PermissionError` (403)	`6`	Confirm the key belongs to the right organization and scope
`api_key_invalid`	`2`	The key is malformed or wrong — create a new one
`api_key_revoked`	`2`	The key was revoked — issue a new key in Settings → Developers

See CLI errors for the full exit-code contract.

FAQ

Can I authenticate just one command?

Yes. Put --api-key sh_live_xxx before the subcommand. It overrides any env var or .env for that invocation only.

Is `staplehire init` still supported?

Yes — init is a deprecated alias for login. Both work; prefer login.

What does the `--profile` flag do?

It is reserved for multi-profile authentication and is not active yet. Use --api-key or STAPLEHIRE_KEY to switch organizations today.

Related: Installation · Use in CI · CLI errors

Get started

Workflows

Automation

Reference

Log in with your browser

How the API key is resolved

Use an API key for agents and CI

Log out

Common errors

FAQ

​Log in with your browser

​How the API key is resolved

​Use an API key for agents and CI

​Log out

​Common errors

​FAQ

Log in with your browser

How the API key is resolved

Use an API key for agents and CI

Log out

Common errors

FAQ