API keys let scripts, services, and external integrations sign in to Yellow without a human in the loop. This guide is for organization owners who issue keys to their team or to service accounts. For user-owned keys (yours, tied to your account), see Your profile and settings.

What an API key is

An API key is a long, opaque string that authenticates a request as a specific actor in the platform. The actor can be:

  • A user — the key acts on behalf of that user. Sees what the user sees, can do what the user can do.
  • A service account — a non-human actor created specifically for automation. It has its own membership in an organization and its own role assignments, kept separate from any real person.

Service accounts are the recommended shape for integrations: when the engineer who set up the integration leaves, the key keeps working because it does not depend on a personal account.

Issuing a key

From the organization page → API keys → + New key:

  1. Owner — the user or service account the key authenticates as.
  2. Name — what you want to remember it as ("Stripe webhook", "Nightly report job").
  3. Scope — which tenants and capabilities the key can touch. Often narrower than the owner's full permissions, so the key only does the one job it was issued for.
  4. Expiry (optional) — a date after which the key stops working. Recommended for short-lived integrations.
  5. Save.

The key value is shown once, at issuance. Copy it immediately into the consuming system's secret manager. Yellow does not store the plaintext value — if you lose it, you must rotate to a new key.

Capabilities and scope

A key cannot do more than its owner can. If the owner is a service account with the Sales editor role on the CRM schema, the key can only edit CRM data. Issuing a key does not elevate permissions — you grant capabilities to the owner first, then issue the key.

For minimum-privilege keys, create a dedicated service account per integration, give it only the roles the integration needs, then issue the key.

Rotating a key

When you rotate a key, Yellow issues a new value and immediately invalidates the old one. From the key's row, click Rotate, copy the new value, update the consuming system.

Rotate proactively:

  • Every 90 days for any production-touching key, as a hygiene baseline.
  • Immediately if you suspect a leak (the key was in a public commit, a shared screen, an old laptop).
  • When a team member who knew the value leaves.

Revoking a key

Revoke kills a key permanently. The consuming system starts failing on its next request — there is no grace period. Use revocation for one-shot keys that have served their purpose, or for compromised keys when rotation is not enough.

Auditing key usage

Each key carries metadata you can inspect:

  • Last used — the most recent successful request.
  • Issuer — who created the key.
  • Owner actor — who the key acts as.

Long-stale keys (last used months ago, no apparent purpose) are good rotation or revocation candidates. Yellow does not delete them automatically.

Security checklist

  • Issue a separate key per integration; never share one across consumers.
  • Use service accounts, not personal users, for automation.
  • Set expiries on short-lived keys.
  • Store keys only in a secret manager — never in source control, never in shared documents.
  • Revoke keys for departing team members the same day.