Authentication#

Current Authentication

Brandwave currently uses session access tokens for authentication. API keys are planned for a future release and will be tracked in Rock #13. This page documents the planned API key authentication system.

When implemented, the Brandwave API will use API keys for authentication. You'll include your key in the Authorization header of every request.

Getting your API key#

API keys are managed in your organisation settings. Each key is scoped to a single organisation and inherits the permissions of the user who created it.

Sign in to your Brandwave dashboard
Navigate to Organisation Settings
Select the API Keys tab
Click Create API Key and give it a descriptive name

Keep your key secret

API keys grant full access to your organisation's data. Never commit them to version control, expose them in client-side code, or share them publicly.

Using your API key#

Pass your API key as a Bearer token in the Authorization header.

bash

curl https://api.gobrandwave.com/v1/activities \
  -H "Authorization: Bearer bw_live_abc123def456"

SDK authentication#

If you use the TypeScript SDK, pass the key when creating the client. The SDK handles the header automatically.

Current SDK Authentication

The SDK currently requires an accessToken (session token) instead of an API key. When API keys are implemented, the SDK will accept either method.

typescript

import { createBrandwave } from '@brandwave/ts';

const bw = createBrandwave({
  accessToken: process.env.BRANDWAVE_ACCESS_TOKEN,
});

Error responses#

Authentication errors return a 401 Unauthorized status with a JSON error body.

json

{
  "error": "unauthorized",
  "message": "Invalid or expired API key."
}

Common causes#

Missing Authorization header
Incorrect key format (must start with bw_live_ or bw_test_)
Revoked or expired API key
Key does not belong to the requested organisation

Test vs. live keys

Use bw_test_ prefixed keys during development. Test keys have the same permissions but operate on sandbox data that won't affect your production metrics.