Skip to content
northstar
Docs menu

API keys

Create, store, send and revoke the keys that authenticate an integration account.

In short

An API key authenticates an integration account: every call made with the key acts as that account, with its roles and teams. A key is shown once, when it is created. Northstar only keeps a fingerprint of it. A key works until it is revoked: rotate keys by creating a new one before revoking the old one.

Create a key

  1. Open Developers from your account menu, then the integration account.
  2. Under API keys, click Create API key and give it a Key name, for example "production" or "staging".
  3. Copy the key that appears. It will not be shown again.

Keys start with northstar_. The list then shows each key's name, its first characters (Prefix), its status (Active or Revoked), when it was created and when it was last used.

A key belongs to the organization you created it in. The account must stay a member of that organization for the key to work.

Store it safely

  • Put the key in your secret manager, or in the environment of the process that runs your code, as NORTHSTAR_API_KEY.
  • Never write it in the code, a notebook, a ticket or a repository.
  • Use one key per environment (production, staging, a developer laptop), so you can revoke one without stopping the others.

If a key is lost, nobody can recover it, not even an administrator: create a new one.

Send it with each call

The Python SDK sends the key for you. For a raw HTTP call, send it in one of these headers:

http
X-API-KEY: northstar_…
Authorization: Bearer northstar_…

A missing, unknown or revoked key gets a 401 Unauthorized answer.

How long a key works

A key has no expiry date. It stops working as soon as:

  • it is revoked;
  • its integration account is banned or deleted;
  • its integration account is removed from the organization.

Changing the account's roles or teams does not change the key: the next call simply gets the new rights.

Rotate or revoke a key

To rotate a key without interruption:

  1. Create a new key on the same account.
  2. Deploy it where the old one was used.
  3. Wait until the old key's last used date stops moving.
  4. Revoke the old key.

Revoke stops a key immediately and cannot be undone. Revoke at once a key that may have leaked, then create a new one.

FAQ

Can I see a key again after creating it? No. Northstar stores only a fingerprint of it. Create a new key if you lost it.

Can one key work in several organizations? No. A key belongs to the organization it was created in.

How do I know which key a pipeline uses? Compare the key's first characters with the Prefix column, and check its last used date.

See also