Managing Multiple API Keys

Each BounceBan account can have up to 100 API keys. Give each tool, integration or environment its own key. You can then see how much each key uses, limit how many credits it can spend, and turn it off without affecting your other keys.

Your existing API key was kept as a key named Default. It never expires and has no quota, so your existing integrations keep working without any changes.

• Shared by all keys of an account: the credit balance (team members use the team's shared credits, as before), concurrency, API rate limits and the IP whitelist.
• Set for each key: name, expiry date, daily and monthly quotas, and whether the key is enabled or disabled. Usage is also tracked for each key.

Go to API settings: https://bounceban.com/app/api/settings. The API Keys table shows each key's name, key value (partly hidden), status (Active, Disabled or Expired), expiry date (UTC), quota (used / limit) and creation date.

1. Click Create API key.
2. Enter a Name of 1 to 64 characters, for example the tool or integration that will use this key.
3. Optionally, pick an Expiry date (UTC). Leave it empty if the key should never expire.
4. Click Create.

When you have 100 keys, the Create API key button is disabled. Disabled and expired keys count toward the limit; deleted keys don't. To free a slot, delete a key you no longer use.

• Only the first and last 4 characters of a key are shown. Click the copy icon next to it to copy the full key. You can copy a key at any time.
• Click a key's name to rename it. Renaming doesn't affect requests that use the key.

Open the Actions menu on a key's row:

• View usage: opens the API usage page for this key (see "Track usage for each key" below).
• Roll key: replaces the key with a new value. The old value stops working right away, and this can't be undone. The key keeps its name, expiry date, quota and usage history. Update your integration with the new value.
• Set expiry date: pick a date (UTC), or clear it so the key never expires. The key works until 23:59:59 UTC on that date. The date can't be in the past.
• Set quota: limits the credits this key can use per day or month (see "Daily and monthly quotas" below).
• Disable / Enable: requests that use a disabled key are rejected right away. You can enable it again at any time.
• Delete: requests that use the key are rejected right away. This can't be undone.

Changes to a key (roll, disable, enable, delete, expiry date and quota) take effect within seconds.

If a key expires within the next 7 days, we send a reminder email to the account the key belongs to. Each expiry date is reminded once, and keys that expire soon are listed in one email. If you change a key's expiry date, you'll get a new reminder for the new date. Disabled keys don't get reminders.

A quota is the maximum number of verification credits a key can use. Choose Set quota in the key's Actions menu:

• Daily quota resets at 00:00 UTC every day.
• Monthly quota resets at 00:00 UTC on the 1st day of each month.
• You can set one or both. Leave a field empty for no limit. A quota must be a whole number from 1 to 100,000,000.
• The Quota column in the key table shows how much of the current day's and month's quota has been used.

• Single verification (including the waterfall endpoint), bulk verification and bulk file uploads count.
• /v1/check uses the separate Check credits and doesn't count.
• Credits refunded for unknown results go back to the key's quota for the day and month in which they were charged.
• If you add a quota to a key that had none, the credits the key already used in the current day and month count toward the new quota.

• A request or bulk task that needs more credits than the key has left is rejected as a whole with HTTP 403. Bulk tasks are never partially accepted, and no credits are charged for the rejected request.
• For bulk file uploads, the quota is checked when the file is uploaded and again when it is imported. If other requests used up the quota in between, the task is canceled without charging credits, and you receive an email.
• The key can verify again after the quota resets, or right away if you raise or remove the quota.
• A quota only adds a limit to the key. Your account still needs enough credits.

Click View usage on the API settings page, or go to https://bounceban.com/app/api/usage.

• Show All API keys or one key, for the last 7, 30 or 90 days.
• The page shows:
  • a daily chart
  • a By API key table with requests, credits used, deliverable, undeliverable, risky and unknown counts, check credits, and a link to the key's bulk tasks
  • Requests by endpoint
  • recent single verifications via the API (last 7 days) with the key and request IP
• Click Download CSV to export the data.
• Dates are in UTC. The data is updated about every 5 minutes and kept for 90 days.
• Credits used = credits charged minus credits refunded (for example, for unknown results). A refund can be counted on the day after the charge.
• Deleted keys are shown with "(deleted)".

The API key is also shown in these places:

• Bulk verification tasks: filter API tasks by API key (shown when you have more than one key).
• Credits usage history (Account > Usage): your API records show the API key and request IP, including in the CSV export.

• API keys belong to the account that created them. Each team member manages their own keys (up to 100). The team owner and admins can't see, disable or change a member's keys.
• Members' keys use the team's shared credits. When the owner views a member's credit usage, the member's API key and IP are not shown.
• If a member is deactivated through SCIM (SSO), all of that member's keys are replaced with new values, so the old values stop working.

You no longer need extra team accounts just to get more API keys. Learn more about teams: Share credits with team.

Send any active key of your account in the Authorization header, without a Bearer prefix:

• All keys of an account can access the account's verification results and bulk tasks.
• If a key is disabled or expires, tasks already submitted with it keep running. You can fetch their results with any other active key of the same account.
• After you roll or delete a key, requests that use the old value are treated as an invalid key.

Errors are JSON with a human-readable msg. Key-specific errors also include error, a stable code you can check in your code. Don't retry 401 or 403 errors automatically.

• 401 (no error field): the API key is missing or invalid (including a rolled or deleted key), the IP address isn't whitelisted, or the account is blocked. See msg.
• 401 – api_key_disabled: the key has been disabled.
• 401 – api_key_expired: the key has expired.
• 403 (no error field): the account doesn't have enough credits. See credits_required and credits_remaining.
• 403 – api_key_quota_exceeded: the key has reached its daily or monthly quota. Don't retry before quota_resets_at.
  • quota_period: daily or monthly
  • quota_resets_at: when the quota resets (ISO 8601, UTC)
  • credits_remaining: credits left in the key's quota
• 429 (rate limited): Back off and retry.

Example of a key over its daily quota:

Full API reference, including the API keys and Errors sections: https://bounceban.com/public/doc/api.html