API keys
Creating a machine credential, what it can do, how to use it, and how to revoke it.
An API key lets a script or another system act on your workspace without a person signing in.
Creating one
Settings → API keys → New key. Give it a name that says what will use it — nightly-order-export, not key1 — because the name is the only thing you will have to go on when deciding whether it is still needed a year from now.
The key is shown once, at creation. It is stored as a hash, so nobody, including us, can display it again. Losing it means creating a new one and revoking the old.
A key looks like juno_live_…. The first fourteen characters are kept in plain text purely so the list can identify which key is which; the rest is never stored.
Using one
Send it as a bearer token:
Authorization: Bearer juno_live_4f2a…The workspace comes from the key, not from anything you send — every request is scoped to the workspace the key belongs to, and there is no way to address another one.
What a key can do
A key cannot be more powerful than the person who created it. Its permissions are the intersection of what you asked for and what you yourself hold, so an Agent cannot mint an administrator.
Ask for the narrowest set that works. A key that exports contacts needs contact.view and nothing else; one that only sends messages does not need to read them.
A key acts as a machine principal — it has no user and no membership. Anything that requires a person (changing a password, accepting an invite) is not available to it.
Revoking one
Revoke on the key's row. It stops working immediately; nothing needs restarting on your side, and requests made with it return 401.
Revoke rather than delete: the row stays, so the audit trail still says which key did what.
Three moments worth revoking on:
- A key was pasted somewhere it should not have been — a repository, a ticket, a screenshot.
- The integration it was made for was switched off. An unused key is only risk.
- Someone with
api_key.createleft the company.
Habits worth having
- One key per integration. A shared key cannot be revoked without breaking everything at once, which is why nobody ever revokes it.
- Never in the client. A key in a browser or a mobile app is a published key, however it is obfuscated. The web widget exists precisely so a page needs no key.
- Check
last used. A key nobody has used in months is a key to revoke. - Rotate before you have to. Create the new one, move the integration over, revoke the old one — in that order, so nothing is down between steps.