Skip to main content
Black Hair API uses API key authentication. Every request to a /v1/ endpoint must include your personal API key in the X-API-Key HTTP header. There are no session cookies, OAuth flows, or JWT tokens — just a single header on every call. This keeps integration straightforward regardless of the language or framework you are using.

​
Your API key

When you subscribe at blackhairapi.com/pricing, your API key is generated immediately and delivered to your inbox. Every key begins with the bha_ prefix, making it easy to identify in logs and code reviews: 
bha_A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8
Your API key grants full access to your quota and billing tier. Do not share it publicly, do not embed it in client-side JavaScript, and do not commit it to source control. If your key is ever exposed, contact support immediately to have it rotated.
The safest way to handle your key is to store it as an environment variable and read it at runtime: 
export BLACK_HAIR_API_KEY="bha_your_api_key_here"

​
Passing your key

Include the key in the X-API-Key header on every request. The header name is case-insensitive, but X-API-Key is the canonical form used in all examples and error messages. 
curl https://api.blackhairapi.com/v1/products/ \
  -H "X-API-Key: bha_your_api_key_here"

​
Authentication errors

When a request cannot be authenticated or has exceeded its allowed quota, the API returns one of the following error responses:
Status codeErrorCause
401 UnauthorizedAPI key required.The X-API-Key header is missing from the request.
401 UnauthorizedInvalid or expired API key.The key value is incorrect, has been rotated, or the account has been deactivated.
429 Too Many Requestsrate_limit_exceededYou have exceeded your plan’s per-minute request limit. The response body includes a retry_after_seconds field.
429 Too Many Requestsmonthly_limit_exceededYou have used all of your plan’s monthly requests. Your quota resets at the start of the next calendar month.
A 429 response body looks like this: 
{
  "detail": {
    "error": "rate_limit_exceeded",
    "message": "Too many requests. Your starter plan allows 5 requests per minute.",
    "retry_after_seconds": 42
  }
}
When you receive a 429, wait for the number of seconds indicated in retry_after_seconds before retrying. For monthly limit errors, consider upgrading your plan.

​
Keeping your key secure

Follow these practices to keep your API key safe:
  • Use environment variables. Read the key from process.env or os.environ at runtime rather than hard-coding it.
  • Use a secrets manager. In production, store keys in a service such as AWS Secrets Manager, HashiCorp Vault, or Doppler.
  • Add it to .gitignore patterns. If you use a .env file locally, make sure .env is listed in .gitignore before your first commit.
  • Restrict access. Only the services and team members that call the API directly should have access to the key.
  • Rotate regularly. Treat your key like a password — rotate it periodically and immediately after any suspected exposure.
For a full breakdown of request limits by plan tier — including per-minute caps and monthly allowances for Starter, Growth, Pro, and Enterprise — see Plans & Limits.