# Create an API key

## Prerequisite

API keys can only be created by users with the **Admin** role. The API is available from the **Standard plan** upwards. On the Compact plan API access is not enabled.

---

## Create an API key

1. Go to **Settings > Developer > API keys**.
2. Click **Create new API key**.
3. Give it a descriptive name, for example "CRM integration" or "Office sync script".
4. Choose the **scope**:
   - *Read-only:* may fetch data but cannot write or delete anything.
   - *Full:* may read, write and delete (matches the access rights of the person creating it).
5. Click **Create key**.

The generated key is **shown in plain text exactly once**. Copy it immediately and store it securely (for example in a password manager). After the dialog closes, the key can no longer be viewed. Only the name and the last four characters remain visible.

---

## Use the key in an HTTP request

Send the API key as a bearer token in the `Authorization` header:

```
GET /api/v1/credentials HTTP/1.1
Host: api.reosa.de
Authorization: Bearer <your-api-key>
Content-Type: application/json
```

Replace `<your-api-key>` with the full key string. Use HTTPS only. Requests over plain HTTP are rejected.

---

## Rate limits

| Plan | Requests per minute | Requests per day |
|---|---|---|
| Standard | 60 | 5,000 |
| Max | 300 | 50,000 |

If you exceed the limit, the API responds with HTTP status `429 Too Many Requests`. The `Retry-After` header contains the number of seconds until the next allowed request.

---

## Rotate or revoke a key

**Rotate:** if you suspect a key has been compromised, create a new key immediately and revoke the old one. Between the two steps there is a short window in which both keys are active, so you can switch integrations over without downtime.

**Revoke:** in the key list, open the three-dot menu next to the key and choose **Revoke key**. The key becomes invalid immediately. Requests with a revoked key receive HTTP status `401 Unauthorized`.

---

## Security notes

- **Never** store API keys in source code or version control systems.
- Use a separate key with the smallest possible scope for every integration.
- Monitor key usage under *Settings > Developer > API logs* and revoke keys that are no longer used.
- All API requests are recorded in your workspace's audit log.