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

:::note
While the API Key resource supports standard CRUD operations internally, it is **not publicly accessible** via public REST API endpoints. It is strictly managed via the administrator dashboard.
:::

:::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** — Create a new one to rotate credentials. Update your services with the new API Key and Secret before pausing and archiving the old key.
5. **Revoke instantly** — Pause the API Key to disable it. You can later archive the API key.

---

## Creating an API Key

To create an API Key, you can use the Gamopanda dashboard. Navigate to Settings > API Keys > Create API Key and follow the instructions.


:::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** — Create a new key in the Gamopanda dashboard 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. **Pause the old key** — Pause the old key in the Gamopanda dashboard.
5. **Archive the old key** — Archive the old key in the Gamopanda dashboard.

---

## Revoking a key

To temporarily suspend a key without deleting it, click the pause button in the API Keys section in your Gamopanda dashboard.
You can later archive the API key.

---

## Access & permissions

| Caller | Allowed operations | Notes |
|---|---|---|
| Admin | CREATE · GET · LIST · UPDATE · DELETE | Managed via the internal admin UI only |
| 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`) |