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 or invalid, or can no longer be used, the API returns a 401 error. Those requests still count toward the per-IP rate limit, so a client that keeps retrying a rejected key can get 429 rate_limited instead.

revoked_api_key covers two situations, and message tells you which one it is:

  • The key itself has been revoked. It will never work again. Create a new key from the dashboard.
  • The account the key belongs to is no longer active, for example because its subscription has ended. For a team account, this also happens while the team leader's account is inactive. The key is not revoked: it works again as soon as the account is reactivated, with nothing to change on your side.

Build your error handling on code, which stays the same. message is written for people and may change.

Invalid API key response

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

Revoked API key response

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

Inactive account response

{
  "error": {
    "code": "revoked_api_key",
    "message": "The account this API key belongs to is no longer active. The key works again once the account is reactivated.",
    "details": null
  }
}

For a teammate whose team leader's account is inactive, message reads: The team leader's account is no longer active, which suspends every teammate's API keys. This key works again once the team leader's account is reactivated.

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.

Was this page helpful?