API keys

An API key authenticates a request. The key belongs to one organisation. Send it as a bearer token.

Authorization: Bearer YOUR_API_KEY

curl -X POST "https://api.binlookupapi.com/v1/bin" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number": 42467101}'

The request rules are in the API reference.

Who can manage keys

Every member can see key names and the first characters of each key. No member can see a full key after it is created. Role definitions are on the team page.

Create a key

1. Open API Keys.
2. Enter a name. The name must have 1 to 100 characters.
3. Select Create Key.
4. Copy the key and store it outside the dashboard.

CAUTION: The dashboard shows the full key one time only.

Keys start with blapi_live_. After creation, the table shows the first characters of the key. The dashboard also shows a curl command that contains the new key.

Key status

You cannot set an expiry date in the dashboard. A key does not expire unless BINLookupAPI sets an expiry date for you.

The table also shows the name, the key prefix, and the creation date.

Rename, revoke, and rotate

Rename a key

1. Open API Keys.
2. Select Rename next to the key.
3. Enter the new name.
4. Select Save.

Revoke a key

CAUTION: You cannot undo a revocation. The key stops immediately.

1. Open API Keys.
2. Select Revoke next to the key.
3. Confirm the action.

Create a new key when you need a replacement. A revoked key cannot be activated again.

Rotate a key

Use these steps to replace a key without a gap.

1. Create a new key.
2. Change the application to use the new key.
3. Confirm that the new key returns HTTP 200.
4. Revoke the old key.

If a key is exposed, create a new key, switch the application, and then revoke the exposed key.

Protect a key

• Store the key in an environment variable or a secrets manager.
• Do not put the key in source control.
• Do not put the key in browser code or in a mobile application.
• Create one key for each environment, such as development, staging, and production.
• Create one key for each service that calls the API.
• Revoke keys that you do not use.

All keys in one organisation share the daily quota.

A missing or rejected key returns HTTP 401:

{
  "error": "UNAUTHORIZED",
  "message": "Missing, invalid, revoked, or expired API key"
}

See HTTP 401.

How the key is stored

BINLookupAPI stores a hash of the key. The full key is not stored. The dashboard cannot show it again. See Security.

Related pages

• Quickstart
• API reference
• Team roles
• Security
• JavaScript guide