Skip to content

Keep your key safe

Where to store a key, how to limit what it can do, and what to do when it is exposed.

Version v1.1, updated

On this page

Anyone who holds an API key acts as your company, within the scopes of that key. Treat it like a password, from the moment you copy it.

Store it as a secret

  • Keep the key in a secrets manager or in an environment variable of the server that calls the API.

  • Never put a key in a web page, a mobile app or any code that runs on a customer device.

  • Never write a key in source code, a ticket, a chat or a log line.

  • Send it only in the Authorization header, never in a URL or a query string.

Keys start with birp_live_, followed by 32 letters and digits. Configure your secret scanner with this format, so a key committed by mistake is found at once.

Give each key as little as possible

  • Use one key per system, so you can revoke one without stopping the others.

  • Choose the smallest set of scopes that works. A system that only reads stock needs no write scope.

  • Set an expiry date, and create the next key before the current one expires.

  • Rotate keys after a team change: create a new key, switch the system to it, then revoke the old one.

When a key is exposed

  1. Revoke the key in BIRP at once, under Settings, then API keys.

  2. Create a new key with the same scopes and give it to the system.

  3. Check the key list: it shows when the revoked key is still being tried. The key name tells you which system still holds it.

When you write to support

Quote the request_id of the response, never the key. Every response carries it, in the X-Request-Id header and in every error body.

Related

  • first-key
  • scopes
  • errors-overview