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

# Authentication

> Authenticate Public API requests with the x-api-key header.

Send your organization API key on every request. Keys are scoped to one organization and respect the permissions you configured when creating the key.

## Header

```bash theme={null}
x-api-key: sv_org_your_api_key
```

| Rule        | Detail                                                 |
| ----------- | ------------------------------------------------------ |
| Header name | `x-api-key`                                            |
| Scope       | One organization per key                               |
| Permissions | Missing permissions return `403` even with a valid key |

## Create a key

1. Open **Integrations → API keys** in the SquadVault dashboard (also reachable from the [Integrations](/user-guide/integrations) hub).
2. Create a key and select the permissions you need.
3. Copy the secret once — store it in an environment variable such as `SQUADVAULT_API_KEY`.

<Warning>
  Treat API keys like passwords. Do not commit them to source control or share them in Discord.
</Warning>

## Example

```bash theme={null}
curl -X GET "https://api.squadvault.xyz/v1/players/YOUR_ORG_ID" \
  -H "x-api-key: $SQUADVAULT_API_KEY"
```

```javascript theme={null}
const response = await fetch(
  "https://api.squadvault.xyz/v1/players/YOUR_ORG_ID",
  {
    headers: {
      "x-api-key": process.env.SQUADVAULT_API_KEY,
    },
  },
);
```

## Auth failures

| Status | `error`         | Meaning                                       |
| ------ | --------------- | --------------------------------------------- |
| 401    | `unauthorized`  | No valid session or API key                   |
| 401    | `invalidApiKey` | Key missing, expired, revoked, or invalid     |
| 403    | `forbidden`     | Key valid but wrong org or missing permission |
| 429    | `rateLimited`   | Key exceeded its request rate limit           |

See [Errors](/api/errors) for the shared error body shape.