> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bigspin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Bigspin API Authentication: API Keys and Bearer Tokens

> Learn how to generate a Bigspin API key and pass it as a Bearer token in every API request, plus how to handle authentication error responses.

Every request to the Bigspin public API must include an API key. API keys authenticate your requests and tie them to your workspace, which determines which projects and transcripts you can access. New keys use the `sk-bigspin-api03-` prefix so you can identify them at a glance.

<Note>
  Legacy keys with the `sk-prism-api03-` prefix (issued before the Bigspin rename) are still accepted — you do not need to rotate them. New keys you create today will use `sk-bigspin-api03-`.
</Note>

## Getting an API key

<Steps>
  <Step title="Open API Keys settings">
    In the Bigspin dashboard, navigate to **Settings → API Keys**.
  </Step>

  <Step title="Create a new key">
    Click **Create API Key**, give it a descriptive name (for example, `production-prompt-fetcher`), and optionally add a description. Then click **Create API Key**.
  </Step>

  <Step title="Copy the key immediately">
    Bigspin shows the full key only once. Copy it to a secure location — a secrets manager, environment variable, or vault — before closing the dialog.
  </Step>
</Steps>

<Warning>
  Bigspin cannot show you the full key again after you close the creation dialog. If you lose it, revoke the key and create a new one.
</Warning>

## Including the key in requests

Pass your API key in the `Authorization` header using the Bearer scheme:

```
Authorization: Bearer YOUR_API_KEY
```

Here is a complete example using curl:

```bash theme={null}
curl -X GET "https://app.bigspin.ai/public/api/v1/projects" \
  -H "Authorization: Bearer sk-bigspin-api03-your-api-key" \
  -H "Content-Type: application/json"
```

## Permissions

API keys can be scoped to specific permissions when you create them. The current permissions are:

| Permission       | Grants access to                                  |
| ---------------- | ------------------------------------------------- |
| `projects-read`  | List and read projects, list and read transcripts |
| `projects-write` | Create projects, upload transcripts               |

Leaving an API key with no permission restrictions grants full access. Scope keys to least privilege when integrating with production systems.

<Note>
  Legacy keys may carry a `halfpipe-transcripts-write` permission instead of `projects-write` — both are accepted for the create-project and upload-transcript endpoints, so existing integrations continue to work without changes.
</Note>

<Warning>
  **Response shape change for legacy `/halfpipe/*` routes (2026-05).** `POST /public/api/v1/halfpipe/sessions` and `POST /public/api/v1/halfpipe/transcripts` now return the same response shape as the new `/projects/*` routes: snake\_case fields (`created_at`, `model_name`, `turn_count`), no `success: true` flag, and no `workspaceId` field. If your integration parses `response.success` or `response.data.workspaceId` from these endpoints, update it to read from the new shape. The path and request body are unchanged.
</Warning>

<Note>
  JWT tokens (which start with `ey`) are not supported on most public API endpoints. Always use an API key with the `sk-bigspin-api03-` prefix.
</Note>

## Authentication error responses

When the API cannot authenticate your request, it returns a JSON error body alongside an HTTP error status.

**Missing API key — `401 Unauthorized`**

```json theme={null}
{
  "error": {
    "message": "API key required for authentication",
    "type": "authentication_error",
    "code": 401
  }
}
```

**Invalid API key — `401 Unauthorized`**

```json theme={null}
{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": 401
  }
}
```

**Insufficient permissions — `403 Forbidden`**

```json theme={null}
{
  "error": {
    "message": "API key does not have permission for this endpoint",
    "type": "authorization_error",
    "code": 403
  }
}
```

A `403` response means your key is valid but does not have access to the specific project or transcript you requested. Check that the key was created in the same workspace that owns the resource, and that it carries the right permission (`projects-read` for read endpoints, `projects-write` for create/upload endpoints).

## Managing API keys

From **Settings → API Keys** you can:

* **Revoke** a key to suspend access without permanently deleting it. Revoked keys can be reactivated later.
* **Delete permanently** a key to remove it from the system entirely. This cannot be undone.
* **View last-used timestamps** to audit which keys are still active.

## Security best practices

* Store API keys in environment variables or a secrets manager. Never hard-code them in source files or commit them to version control.
* Create one key per environment (development, staging, production) so you can rotate or revoke them independently.
* Revoke any key immediately if you suspect it has been exposed.
* Rotate keys periodically as part of routine security hygiene.