Opening programmatic access

An API key is there to let in something other than you: a script, an internal tool, an integration.

A key has no rights of its own

This is the part that surprises people, and it is the part that protects you.

A key is attached to an identity in your workspace, and it inherits that identity's rights. It carries no permissions of its own.

Direct consequence: to give a tool restricted access, you do not restrict the key, you attach it to a restricted identity. An integrator who only needs to read contracts gets a key tied to an identity with read-only access on contracts.

The secret is shown only once

At creation, the key is displayed. After that, never again.

Put it in your secrets manager right away, not in a message and not in a notes file.

Closing the door

Revoke a key and the access stops. Three moments when that is the right reflex.

• A contractor finishes an engagement.
• A key may have ended up in a code repository, a ticket or a screenshot.
• One integration is replaced by another.

Revoking costs five seconds. Wondering for six months whether a key is lying around somewhere costs far more.

Good habits

One key per use. The import script and the reporting tool each get their own, otherwise revoking one breaks the other.

An end date when you know it. A contractor key expires at the end of the engagement, without depending on someone remembering.

Never in the browser. A key is used from a server. Put in code that runs on your visitors' machines, it is public the same day.