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. The email is matched without regard to case.
Use of the API with these credentials is subject to the Ruuster API Terms of Use.
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.