> ## 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.

# API Keys: Secure Bigspin Programmatic Access

> Generate, revoke, and rotate API keys to authenticate requests to the Bigspin public API (Projects and Transcripts). Includes security best practices.

API keys are the credentials your code uses to make authenticated requests to Bigspin's public API — including the [Projects](/api-reference/projects) and [Transcripts](/api-reference/transcripts) endpoints. Each key is scoped to your organization's workspace, so any API calls made with a key operate within your organization's data and configuration. Bigspin displays the full key only once — at creation time — so treat generation as a deliberate step and have a secure place ready to store the value before you begin.

## Navigate to API Keys

In the dashboard sidebar, scroll to the organization section and click **API Keys** (identified by the key icon). The page lists all keys created for your workspace along with their name, a masked prefix, status, creation date, creator, and the last time each key was used.

## Create an API Key

<Steps>
  <Step title="Open the creation dialog">
    Click **Create API Key** in the top-right corner of the API Keys page.
  </Step>

  <Step title="Name your key">
    Enter a descriptive name (minimum 3 characters). A good name identifies both the integration and environment, for example `production-transcript-upload` or `staging-projects-read`.
  </Step>

  <Step title="Add an optional description">
    Use the description field to note what this key is used for, which service consumes it, or who owns it. This makes future audits much easier.
  </Step>

  <Step title="Copy the key immediately">
    After clicking **Create API Key**, Bigspin displays the full key value once. Copy it now — you will not be able to retrieve it again. Click **Done** when you have saved the key securely.
  </Step>
</Steps>

<Warning>
  Bigspin shows your API key only once, immediately after creation. If you close the dialog without copying the key, you must delete it and generate a new one. Never share your API key in chat, email, or version control.
</Warning>

## Use an API Key

Pass your key as a Bearer token in the `Authorization` header of every API request:

```bash theme={null}
curl https://app.bigspin.ai/public/api/v1/your-endpoint \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Use environment variables" icon="shield">
    Store your API key in an environment variable (for example, `BIGSPIN_API_KEY`) and reference it in code. Never hard-code a key directly in source files.
  </Card>

  <Card title="One key per integration" icon="key">
    Create a separate, named key for each application or environment. This lets you revoke a single compromised key without affecting other integrations.
  </Card>

  <Card title="Rotate compromised keys immediately" icon="refresh">
    If a key is exposed, revoke or delete it right away and generate a replacement. Update all services using the old key before they encounter an auth failure.
  </Card>

  <Card title="Audit usage regularly" icon="chart-bar">
    Check the **Last Used** column on the API Keys page to spot keys that are no longer active. Delete unused keys to reduce your attack surface.
  </Card>
</CardGroup>

<Tip>
  Add API keys to your `.gitignore` and secret-scanning rules. Many teams also use a secrets manager (such as AWS Secrets Manager, HashiCorp Vault, or Doppler) to inject keys at runtime rather than storing them in environment files that could be checked in accidentally.
</Tip>

## Manage Existing Keys

Each key in the table has an actions menu (the three-dot icon on the right) with the following options:

| Action                 | What it does                                                                                                                           |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Revoke**             | Disables the key immediately. Any requests using this key will fail. Revocation can be undone — use **Reactivate** from the same menu. |
| **Reactivate**         | Re-enables a previously revoked key.                                                                                                   |
| **Delete Permanently** | Removes the key from the system entirely. This cannot be undone.                                                                       |

## If a Key Is Compromised

<Steps>
  <Step title="Revoke or delete the key">
    Open the actions menu next to the exposed key and choose **Revoke** (reversible) or **Delete Permanently** (irreversible). This immediately blocks all requests using that credential.
  </Step>

  <Step title="Generate a replacement">
    Create a new key following the steps above. Give it a clear name that distinguishes it from the compromised key.
  </Step>

  <Step title="Update your services">
    Replace the old key value in every environment variable, secrets manager, or configuration file that referenced it. Redeploy or restart the affected services.
  </Step>

  <Step title="Review audit logs">
    Check the **Last Used** timestamp on your remaining keys and review any unusual activity in your projects to confirm no further unauthorized access occurred.
  </Step>
</Steps>