Getting started

Authentication

One credential, sent one way, on every request. There is no session, no OAuth dance and no second factor to hold — which is exactly why the key itself has to be handled carefully.

The header#

Every endpoint expects your key as a bearer token. Nothing else is accepted — not a query parameter, not a cookie, not a custom header — because a key in a URL ends up in access logs, browser history and the referrer of the next request.

every request
Authorization: Bearer rk_live_8Kd2mQ...

What a key looks like#

A key is rk_, the environment, then 32 URL-safe characters of randomness:

rk_test_8Kd2mQ7pR3vX1nL5tY9wB2cF4gH6jK8m
rk_live_3pQ9vN2mK7xR5tL1yB8wC4fG6hJ0dS2a

The environment is in the key on purpose. A live key pasted where a test key belongs is obvious on sight — in a config file, a log line or a screenshot — instead of being discovered when a real rider arrives at a test address.

PrefixEnvironmentEffect
rk_test_TestReal rows, real prices, no charge, no rider, no email.
rk_live_LiveReal deliveries, real money, real people.

Creating a key#

Keys are minted in the dispatch dashboard — there is no API for creating them, deliberately: a credential that can book real riders should be issued by a person who is signed in, not by another credential.

where
https://rider.rheochat.com/<your-company>/admin/developers

Step by step

  1. Sign in at rider.rheochat.com as the dispatch company owner.
  2. Open Developers in the left-hand sidebar — the last group, below Subscription.
  3. Choose the environment at the top of the page. It opens on Test, which is where an integration should start.
  4. Press New key, and give it a name that says which system will hold it — "Website checkout", "Warehouse tool". Six months from now that name is how you work out which key to revoke.
  5. Copy the key immediately. It is displayed once, on that screen, and cannot be retrieved afterwards.
  6. Repeat under Live when you are ready to move real money. Live keys need the Dispatch Pro plan; test keys are free — see Going live.

Owner only

Only the dispatch company owner can see or mint API keys. An invited team member — a dispatcher, a finance user — gets 403 on that page however their role is configured, because a key is not scoped to the permissions of whoever created it: it can do everything the API can do.

You may hold up to five active keys per environment. That is enough to rotate without downtime and to give each system its own key, and few enough that the list stays auditable. Revoke one to make room for another.

A key is shown once

We store only a SHA-256 hash of your key, so there is genuinely nothing to show you later: the plaintext does not exist anywhere after the page that created it. Copy it into your secret store immediately. A key you have lost is replaced, not recovered.

The dashboard lists keys by their prefix — rk_live_3pQ9vN2m… — which is enough to recognise a key without being enough to authenticate with it.

The endpoints behind that screen

These are dashboard endpoints, authenticated by your logged-in session and your team permissions, not by an API key. They are documented so you know what the screen does, not so you can drive key creation from a script.

GET/api/dispatch/admin/api-keys
POST/api/dispatch/admin/api-keys
DELETE/api/dispatch/admin/api-keys/{id}

Storing a key#

  • Server-side only. Never in a browser bundle, a mobile app, or anything compiled and shipped to a device you do not control.
  • In the environment, not the repository. A key in git is a key in every clone, every fork and every CI cache that ever pulled it.
  • One key per system. Your website and your warehouse tooling should hold different keys, so revoking one does not take the other down — and so last_used_at tells you something.
.env
# .env — never committed
RHEOCHAT_API_KEY=rk_live_8Kd2mQ7pR3vX1nL5tY9wB2cF4gH6jK8m
node
// Server-side only. Anything you ship to a browser is public,
// and a live key in a bundle is a key you have given away.
const res = await fetch("https://api.rheochat.com/api/v1/dispatch/quote?…", {
  headers: { Authorization: `Bearer ${process.env.RHEOCHAT_API_KEY}` },
});

Rotating and revoking#

Revocation is immediate: the next request with that key gets 401. Because keys are retired rather than deleted, the record of what had access — and what it did, since every delivery stores the key that created it — outlives the key itself.

Rotate without downtime

  • Mint the new key.
  • Deploy it to the system that holds the old one.
  • Watch the old key's last used timestamp stop moving.
  • Revoke the old key.

If a key leaks, revoke first

Revoke immediately, then work out the blast radius. Deliveries created by a key are listed against it, so you can see exactly what it did while it was out in the world.

When authentication fails#

StatusCodeWhat happened
401missing_api_keyNo Authorization: Bearer … header at all.
401invalid_api_keyMalformed, unknown, or revoked — deliberately indistinguishable.
403company_inactiveThe key is good; the company is suspended, unapproved, or has bookings switched off.
401 response
{
  "error": {
    "code": "invalid_api_key",
    "message": "That API key is not valid or has been revoked."
  },
  "request_id": "0b1c2d3e-4f50-6a7b-8c9d-0e1f2a3b4c5d"
}

A revoked key and a key that never existed return the same message. Telling them apart would tell an attacker whether they hold a real, retired credential — which is a fact worth having and not one we owe them. See Errors and retries for the full vocabulary.