Authentication

You'll need to authenticate your requests to access any of the endpoints in the Brandsearch API. In this guide, we'll look at how authentication works.

API key authentication

The Brandsearch API uses API key authentication. Include your API key in the X-API-Key header with every request.

Example request with API key

curl https://api.brandsearch.co/v1/brands \
  -H "X-API-Key: bsk_your_api_key"

Your API key starts with the bsk_ prefix and is tied to your account. You can create and manage API keys from the Brandsearch dashboard.

Keep your API key secret. Do not commit it to version control or expose it in client-side code. If you suspect your key has been compromised, revoke it immediately from the dashboard and create a new one.

Using the API key

Here's how to include the API key in different languages:

GET

/v1/brands

curl -G https://api.brandsearch.co/v1/brands \
  -H "X-API-Key: bsk_your_api_key" \
  -d page_size=10

Error responses

If your API key is missing, invalid, or has been revoked, the API will return a 401 error:

Invalid API key response

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid.",
    "details": {}
  }
}

Revoked API key response

{
  "error": {
    "code": "revoked_api_key",
    "message": "This API key has been revoked.",
    "details": {}
  }
}

Quota headers

Every authenticated response includes headers showing your current quota usage:

Name
X-Quota-Daily-Remaining
Type
integer
Description
Number of requests remaining for the current day.
Name
X-Quota-Monthly-Remaining
Type
integer
Description
Number of requests remaining for the current month.
Name
X-Quota-Daily-Limit
Type
integer
Description
Your total daily request limit.
Name
X-Quota-Monthly-Limit
Type
integer
Description
Your total monthly request limit.
Name
X-RateLimit-Limit
Type
integer
Description
Maximum requests allowed in the most-constrained rate-limit window.
Name
X-RateLimit-Remaining
Type
integer
Description
Requests remaining in that window after the current one.
Name
X-RateLimit-Reset
Type
integer
Description
Unix timestamp (seconds) when the most-constrained window expires.

Learn more about rate limits and quotas

OpenAPI spec

The full OpenAPI 3.1 spec is published at https://api.brandsearch.co/v1/openapi.json (no auth required). Two interactive viewers are also available:

Swagger UI — https://api.brandsearch.co/v1/docs
ReDoc — https://api.brandsearch.co/v1/redoc

The spec declares X-API-Key as the global security scheme, so you can paste your key into any compatible client to make authenticated requests.