Skip to content

Create your first key

Create an API key in BIRP, choose its scopes and expiry, and copy it once.

Version v1.1, updated

On this page

An API key lets a system call the API for one company. An administrator of that company creates it in BIRP and chooses what it may do.

Before you start

You need an administrator account of the company in BIRP. API access is enabled for each company: if your first call answers 403 api_access_disabled, ask BIRP support to enable it.

Create the key

  1. In BIRP, open Settings, then API keys.

  2. Choose Create key.

  3. Give the key a name that says which system uses it, for example "Online shop".

  4. Pick the integration the key is for. BIRP uses it for statistics only.

  5. Choose the scopes: what the key may read and what it may write. Give it only what the system needs, see Scopes.

  6. Choose an expiry date. A key can also never expire, for systems whose keys your team rotates itself: see Keep your key safe.

  7. Create the key and copy it at once. BIRP shows it this one time and never again.

Warning. If you lose the key, you cannot see it again. Revoke it and create a new one.

Revoke a key

Revoke a key in the same list when a system no longer needs it, or at once if it may be exposed. From the next request on, the key answers 401 api_key_revoked.

The key list shows when a revoked or expired key is still being used, so you can find the system that still holds it.

Check the result

Send GET /v1/me with the new key. The answer names the company and the key, with its scopes.

Related

  • keep-your-key-safe
  • first-request
  • scopes