# API Key

API Keys are the credentials used for **admin-level server-to-server authentication** with the Gamopanda API. Each key pair consists of an `apiKey` identifier and an `apiSecret` — both generated by the platform on creation. They are sent as request headers (`x-api-key` and `x-api-secret`) on every admin API call.

:::danger
The `apiSecret` is returned **only once** — at the moment the key is created. It cannot be retrieved again. If you lose it, you must delete the key and create a new one.
:::

---

## How it works

1. **Create an API key** — provide a `name` and optional `description`. The platform generates the `apiKey` and `apiSecret` values automatically and returns the secret in the creation response.
2. **Store the secret securely** — copy the `apiSecret` from the response and store it in your secrets manager or environment variables. It will not be shown again.
3. **Authenticate requests** — include both values as headers on every admin API call:
   ```http
   x-api-key: <your-api-key>
   x-api-secret: <your-api-secret>
   ```
4. **Rotate when needed** — delete the old key and create a new one to rotate credentials. Update your services with the new `apiSecret` before deleting the old key.
5. **Revoke instantly** — set `status` to `paused` to disable a key without deleting it, or `DELETE` to remove it permanently.

---

## Fields

| Field | Type | Required | Notes |
|---|---|---|---|
| `name` | string | ✅ | A unique, human-readable label for this key. Max 256 chars. |
| `description` | string | ❌ | Optional notes about what this key is used for. Max 1 024 chars. |
| `apiKey` | string | — | System-generated identifier. Read-only. Max 32 chars. Returned on every `GET`. |
| `apiSecret` | string | — | System-generated secret. Read-only. Max 64 chars. **Returned on `POST` (create) only** — never again. |
| `status` | enum | ✅ | `draft` · `live` · `paused`. Only `live` keys are accepted for authentication. |

---

## Creating an API key

```http
POST /api/v1.0/schema/apikey/record
x-api-key: <existing-api-key>
x-api-secret: <existing-api-secret>

{
  "name": "Production Server Key",
  "description": "Used by the order service to log streak and challenge activity",
  "status": "live"
}
```

:::warning
The `apiSecret` returned in this response is the **only time it will be shown**. Store it immediately in a secrets manager (e.g. AWS Secrets Manager, HashiCorp Vault, or a `.env` file that is not committed to version control).
:::

---

## Using the key to authenticate

Once created, include both values as HTTP headers on all admin API requests:

```http
GET /api/v1.0/schema/streak/record
x-api-key: abc123def456
x-api-secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

---

## Rotating a key

To rotate credentials without downtime:

1. **Create a new key** — `POST /schema/apikey/record` with a new name.
2. **Deploy the new credentials** — update `x-api-key` / `x-api-secret` in all services that use the old key.
3. **Verify** — confirm all services are using the new key successfully.
4. **Delete the old key** — `DELETE /schema/apikey/record/{old-key-id}`.

---

## Revoking a key

To temporarily suspend a key without deleting it:

```http
PATCH /api/v1.0/schema/apikey/record/{id}
x-api-key: <admin-key>
x-api-secret: <admin-secret>

{
  "status": "paused"
}
```

Requests using a `paused` or `draft` key will be rejected with `401 Unauthorized`.

---

## Access & permissions

| Caller | Allowed operations | Notes |
|---|---|---|
| Admin | CREATE · GET · LIST · UPDATE · DELETE | Full control — admin credentials required for all operations |
| End user | *(none)* | Not accessible |
| Guest user | *(none)* | Not accessible |

---

## Security best practices

- **Never expose credentials in client-side code** — API keys are for server-to-server calls only. The end-user widget uses `x-enduser-access-token` and `x-account-id` instead.
- **One key per service** — create a separate key for each service or environment (staging, production) so you can rotate or revoke them independently.
- **Least privilege by name** — while all admin keys have the same permissions, naming them clearly (e.g. `"order-service-prod"`) makes audit logs easier to trace.
- **Rotate regularly** — establish a rotation policy (e.g. every 90 days) and use the rotation workflow above.

---

## Related resources

| Resource | Description |
|---|---|
| [Introduction](/api-introduction) | Overview of both authentication flows — admin (`x-api-key` / `x-api-secret`) and end-user (`x-enduser-access-token` / `x-account-id`) |

---

## API reference

See the [API Reference](/api/api-key) for full request/response schemas and interactive examples for:

- `GET /schema/apikey/record` — list API keys
- `POST /schema/apikey/record` — create an API key
- `GET /schema/apikey/record/{id}` — get an API key by ID
- `PATCH /schema/apikey/record/{id}` — update an API key
- `DELETE /schema/apikey/record/{id}` — delete an API key