Getting started

Authentication

Every request is authenticated with an API key that belongs to your agency. Keys are created by an agency admin in the portal and are shown exactly once.

Create a key

Sign in to the Roave portal as an agency admin.
Open Team → Integrations and, in the API keys card, choose Create key.
Give the key a name that says where it runs, such as Booking engine — production.
Pick an access level (below) and, optionally, an expiry between 1 and 3,650 days.
Copy the key straight into your secret manager. It is shown once; Roave stores only a hash, so a lost key can't be recovered — create a new one instead.

Keys look like rk_live_ followed by 43 random characters. In the portal list you'll see only the first few characters, when the key was last used, and when it expires.

Send the key

Send the key in the X-API-Key header on every request:

X-API-Key header

curl "https://api.roaveagents.com/api/v1/bookings?limit=5" \
  -H "X-API-Key: $ROAVE_API_KEY"

If your HTTP client only supports bearer tokens, the same key works in the Authorization header:

Authorization header

curl "https://api.roaveagents.com/api/v1/bookings?limit=5" \
  -H "Authorization: Bearer $ROAVE_API_KEY"

Access levels

Level	Can	Use for
Agent (default)	Search, price-check, book, pay for holds, cancel, read vouchers, and read every booking your agency has made.	Almost every integration.
Agency admin	Everything an agent key can, plus the agency-admin parts of the portal API: creating and revoking API keys, managing your team (invites, members, join requests) and onboarding details. It can't sign the distribution agreement — a person signs that in the portal.	Only tooling that manages keys or your team.

A key acts for your whole agency, not for one advisor: it can read and cancel any booking your agency made, whoever made it. Bookings created with a key appear in the portal alongside your team's, attributed to the admin who created the key.

Keep keys safe

Server side only. The API doesn't send CORS headers, so browser code can't call it. Never ship a key in a web page, mobile app or public repository.
One key per system and environment. Separate keys mean you can revoke one integration without taking down the others.
Rotate without downtime. Create the new key, deploy it, confirm traffic has moved (the old key's “last used” stops updating), then revoke the old key.
Revoke immediately if exposed. Revocation takes effect on the next request.

When a key is rejected

A missing, unknown, revoked or expired key returns 401. So does a valid key while your agency's account is suspended or its API access is switched off. A request with no key at all gets the message Unauthorized; a key we can't accept gets the message below.

Response · 401

{
  "data": null,
  "meta": {},
  "error": {
    "code": "unauthorized",
    "message": "Invalid, revoked, or expired API key",
    "details": []
  }
}

A valid key asking for something outside your agency — another agency's booking, say — gets 403 forbidden.

A key created before keys recorded who created them can't search or book: those calls return 403 api_key_owner_missing. An agency admin creates a new key to replace it.