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

# API keys

> Generate, scope, and rotate the API key that authenticates REST API requests.

API keys authenticate your [REST API](/resources/api-reference/overview) requests. A key is issued **per user**, inherits that user's project access and team role, and carries **scopes** that say what it may do. Send it in the `x-api-key` header.

## Generate a key

<Steps>
  <Step title="Sign in to the dashboard">
    Open [dashboard.streampixel.io](https://dashboard.streampixel.io) and sign in.
  </Step>

  <Step title="Open your account menu">
    Click your account name in the top-right corner.
  </Step>

  <Step title="Choose scopes">
    Tick the scopes the key should have. `Upload` and `Read` are on by default; `Control` is off and shows a warning, because a control key can take projects offline and end viewers' sessions.
  </Step>

  <Step title="Request the key">
    Click **Request API Key**. The key is emailed to your registered address and shown once, with its scopes.
  </Step>

  <Step title="Copy and store it">
    Save it in a password manager or secrets store immediately.
  </Step>
</Steps>

<Warning>
  An API key is shown **only once**. If you lose it, generate a new one; the original cannot be retrieved.
</Warning>

## Scopes

| Scope | What the key may do |
| - | - |
| `upload` | Publish and re-distribute builds. |
| `read` | Read projects, build pipeline state, sessions, telemetry, Unreal logs and analytics. |
| `control` | Switch projects on and off, end sessions, choose the active build, change streaming settings. |

Scopes are chosen when you request the key and shown under **Current key** afterwards. They cannot be changed on an existing key: issue a new one with the scopes you need, which replaces the old key.

## Use a key in a request

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl https://platform.streampixel.io/api/v1/projects/projects-status \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={"dark"}
  const res = await fetch('https://platform.streampixel.io/api/v1/projects/projects-status', {
    headers: { 'x-api-key': process.env.STREAMPIXEL_API_KEY },
  });
  ```

  ```python Python theme={"dark"}
  import os, requests

  requests.get(
      'https://platform.streampixel.io/api/v1/projects/projects-status',
      headers={'x-api-key': os.environ['STREAMPIXEL_API_KEY']},
  )
  ```
</CodeGroup>

The two original build endpoints, Upload File and Distribute File, also accept `apiKey` in the JSON body; see their pages.

## Team members and keys

A key can do no more than the person it belongs to:

| Role | Key can |
| - | - |
| Owner, Admin, Editor | Everything its scopes allow, on the projects the member can see. |
| Uploader | Upload and read, plus Set Active Build with the `control` scope; the other control endpoints (enable, disable, end sessions, settings) are refused. |
| Viewer | Read only. |
| Finance | Nothing on the API. |

If a member is removed from the team, their key stops working on that account's projects immediately.

## Rotate a key

Requesting a new key invalidates the previous one at once.

<Steps>
  <Step title="Generate a new key">
    Click **Request API Key** in your account menu.
  </Step>

  <Step title="Update your integrations">
    Replace the old key everywhere it is used: environment variables, CI secrets, deploy configs.
  </Step>

  <Step title="Verify">
    Make a test request. A `401` means an integration still references the old value.
  </Step>
</Steps>

## Security best practices

* **Never commit keys to source control.** Use environment variables or a secrets store.
* **Server-side only.** Do not embed keys in browser bundles, mobile binaries or anything users can decompile.
* **Narrowest scopes.** A CI pipeline needs `upload` and `read`; give `control` only to the automation that switches projects.
* **Rotate on suspected exposure.** Pushed to a public repository by accident: rotate first, then scrub the commit.

## Troubleshooting

| Status | `code` / message | Cause |
| - | - | - |
| `401` | `Authentication required` | Header missing, key rotated, or key mistyped. |
| `403` | `API_KEY_SCOPE` | The key was issued without the scope this endpoint needs. Issue a new key with it. |
| `403` | `Access denied` | The project belongs to another account, or your team role does not allow the action. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.