Authentication

Branches uses Bearer token authentication for every public API endpoint.

Authorization: Bearer <api-key>

API keys are scoped to a workspace. A valid key can only read and write data for its workspace.

Smoke test credentials

Call GET /api/workspace to verify that a key is valid and to identify the workspace it belongs to.

curl https://api.withbranches.com/api/workspace \
  -H "Authorization: Bearer $BRANCHES_API_KEY"

Successful response:

{
  "id": "workspace_123",
  "slug": "acme-health",
  "name": "Acme Health"
}

Missing API key

Requests without a Bearer token return 401.

{
  "error": {
    "type": "invalid_request_error",
    "message": "You did not provide an API key. You need to provide your API key in the Authorization header, using Bearer auth (e.g. 'Authorization: Bearer YOUR_SECRET_KEY')."
  }
}

Invalid API key

Requests with an unknown token return 401. Branches masks the submitted key in the error message.

{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid API Key provided: sk_test_********1234"
  }
}

The response also includes:

WWW-Authenticate: Bearer realm="Branches"

Keep API keys server-side. Do not expose them in browsers, mobile apps, logs, or client-side code.