# Authentication

Source: https://help.ruuster.com/api/authentication

> Send your Ruuster API key and login email as headers. Only owner and admin logins can use the API.

Every request sends two headers:

```
x-api-key: <your Ruuster API key>
x-email:   <the Ruuster login email the key belongs to>
```

These are the same credentials Ruuster's Zapier integration uses. Each key belongs to one person,
except your brokerage's integration key (the key Ruuster set up for your brokerage's app
connections): it works with the login email of any owner or admin of your brokerage, and calls made
that way count as that owner or admin. A personal key also works on its own, without `x-email`,
for clients that can send only one value (an AI assistant's API-key field, say); the integration
key always needs the email, since on its own it names no person. **Only owner and admin logins can use the API**; a key belonging to an agent gets
`403 role_not_permitted`. Every owner or admin key sees the whole brokerage; see
[Scope](https://help.ruuster.com/api/scope). The email is matched without regard to case.

Use of the API with these credentials is subject to the
[Ruuster API Terms of Use](https://help.ruuster.com/api/terms).

**Keep your key secret.** Call the API only from a server. Never put a key in a browser, a mobile
app, a public repository, a URL, or a log. The API refuses browser requests (any request with an
`Origin` header gets `403 browser_not_supported`) and sends no CORS headers.

**If a key leaks**, email support@ruuster.com. Ruuster blocks the key as soon as the report is
handled, usually within the hour during business hours. Calls then get `403 access_revoked` and
the key's webhook subscriptions pause. Ruuster then regenerates a new key for you. Removing a
person from your brokerage in Ruuster also ends their key's access within a few minutes.

**Access states**

| Response | Meaning | What to do |
|---|---|---|
| `401 missing_credentials` | The key header is missing or empty | Send `x-api-key`, with `x-email` |
| `401 invalid_credentials` | Key and email don't match (the same message whether the email is unknown or the key is wrong), or a key sent alone isn't one Ruuster knows | Check both values |
| `401 email_required` | The key sent alone is your brokerage's integration key | Send the owner's or admin's login email in `x-email` with it |
| `403 brokerage_not_enabled` | The key is valid but your brokerage isn't enabled | Have an owner or admin email support@ruuster.com to turn on API access |
| `403 role_not_permitted` | The key belongs to an agent. Only owners and admins can use the API | Use an owner or admin key |
| `403 account_not_eligible` | The login was removed, or isn't a brokerage user | Use another owner or admin key |
| `403 access_revoked` | Ruuster blocked this key | Contact support |
| `503 directory_unavailable` | Ruuster couldn't check the key in time | Retry after a few seconds; this never means the key is bad |

Repeated failed attempts for one email temporarily lock that email out with `429 rate_limited`;
failed attempts with a key alone lock out the network they came from. Wait `Retry-After` seconds.