Docs / How-to guides
Use an API key
Let a script, CI or an agent act as you, with only the permissions and servers you give its key.
An API key lets a script, your CI or an agent act as you, with only the permissions you give it. It reaches the servers you pick, can do only what you allow, and stops when it expires, when you revoke it, or if you leave the workspace.
Make a key
In Settings, under You, open API keys and choose Make an API key. Or, signed in, run:
sokie keys create "GitHub Actions" --from ci --server majestic-lobster-123 --expires 90d
Give it:
- A name, so you can tell keys apart: what uses it, and where.
- An expiry: 7, 30 (the default) or 90 days, a year, or none. Sokie emails you a week before a key expires. A key's expiry can't be extended: make a new key and revoke the old one.
- Servers: every server in the workspace, including ones made later, or only the ones you tick.
- Permissions: start from Read only, Deploy from CI, Agent or Everything, then set any area to No access, Read, or Read and write.
The key is shown once. Copy it then: Sokie keeps only a hash of it.
What a key can do
| Area | Read | Read and write |
|---|---|---|
Servers (servers:) | See servers and their settings | Create them, pause and resume them, change who can call them |
Deploys (deploys:) | See deploys, what each changed, and their files | Deploy, restore and resume |
Tools (tools:) | See tools and what the checks found | Edit tools |
Secrets (secrets:) | See secret names and when each was set | Set and remove secrets |
Logs and usage (logs:read) | Read calls, errors and the month's usage | |
Webhooks (webhooks:) | See webhooks and deliveries | Add and remove them |
Audit trail (audit:read) | Read the workspace's Activity |
Two permissions stand alone: Tool calls (tools:run) gets a 5-minute token to call a server's tools, as the Test tab does, and Also delete servers (servers:delete) lets a key with Servers on read and write delete one.
A key never sees more than you can. Secret values are never readable, with any permission, and billing, members and API keys themselves are never open to a key. A server the key wasn't given is answered as if it weren't there.
Everything a key changes is in Activity as you, via the key: "Ada Lovelace, via GitHub Actions (sokie_ak_9f2a…)".
Use it
Set SOKIE_TOKEN to the key and every sokie command runs as it, instead of this computer's sign-in:
export SOKIE_TOKEN=sokie_ak_… sokie whoami sokie deploy --server majestic-lobster-123
sokie whoami names the key and what it may do. A command the key lacks the permission for stops and says what it needs, and exits 1:
✗ The API key "GitHub Actions" can't set secrets on stripe-billing: it needs Secrets, read and write.
In GitHub Actions, add the key to the repository's secrets as SOKIE_TOKEN and use it in a step's env. For a repository that only deploys one server, a deploy key works too, and is listed on the same page.
Change or revoke a key
Edit changes a key's name, servers and permissions; the key itself, and its expiry, stay the same. Revoke ends it at once: anything using it is refused from its next call. From a terminal, sokie keys lists your keys and sokie keys revoke "GitHub Actions" ends one.