This guide will collect the practices that keep a Roadie integration secure: secret handling, restricted keys, client tokens for apps, and least-privilege management keys. Roadie’s credential model is built for deny-by-default. The practices below are ordered from the most common mistake to the finer-grained hardening.

​
1. Never ship a secret key in a client

A secret key (rd_sk_…) grants full access to your project’s data plane, including minting client tokens. It belongs on your servers only.
  • Anything that runs where a user can read it — a browser bundle, a mobile binary — must not carry a secret key. The SDK’s browser guard throws immediately if it detects a rd_sk_… key in a browser-like environment.
  • Client apps authenticate with a short-lived client token instead, supplied to the SDK through a tokenProvider.
A leaked secret key exposes your whole project. Keep it in server-side secrets management, never in source control or a client build. If one leaks, roll it immediately.

​
2. Choose the credential that fits the job

Roadie has six credential types, each scoped as narrowly as its job allows. Pick the least-powerful one that works: The full model, including how each is sent and enforced, is in Authentication & API keys.

​
3. Scope keys with restrictions

A secret or publishable key can carry allowlists, enforced in the gateway from the config snapshot. Scope every key to exactly what its service needs. Keys are managed on the control plane ():
  • allowed_models — the only provider/model ids (or aliases) the key may request. Anything else fails permission_error / model_not_allowed.
  • allowed_endpoints — the only endpoints the key may call (e.g. chat but not embeddings).
  • max_request_cost_usd — an upper bound on a single request’s estimated cost.
A client token inherits the restrictions of the key that minted it, so restricting the minting key restricts every token derived from it.

​
4. Use client tokens (and device attestation) for apps

For browser and mobile apps, mint short-lived client tokens:
  • Scoped to one end user, carrying that user’s limits, valid for at most an hour.
  • Minted from your backend with a secret key, from a federated identity token with a publishable key (no backend), or — on iOS — from a device attestation with a publishable key (no accounts). See Mobile device auth.
  • A leaked publishable key alone mints nothing: minting still requires a valid identity token or a genuine device attestation, and a client token can never mint another token.
To cut off a compromised session, block the end user — the gateway’s Redis denylist rejects that user within a second across every instance, and the token lapses on its own within the hour.

​
5. Rotate keys with an overlap window

Roll a key rather than deleting and re-creating it, so there is no downtime:
The replacement is issued immediately; the old key stays valid for the overlap window (0–72 h, default 1 h) so you can redeploy. Revocation (DELETE /v1/keys/{keyId}) takes effect in well under a second via the Redis denylist. Revoked or expired keys fail with an authentication_error. For provider (BYOK) keys, follow the BYOK rotation guide — provider secrets are envelope-encrypted, bound to their tenant, and decryptable only by the gateway.

​
6. Keep automation least-privilege

Automate the control plane with a management key (rd_mk_…), not a personal owner session:
  • It is org-scoped and capped at admin — it can never perform owner-only actions (billing, org deletion, issuing another management key, data export).
  • It is verified only by the control plane; the gateway has no knowledge of rd_mk_, so a management key can never call the data plane.
  • Only an org owner can issue one, and revocation is immediate (a live Postgres read, no propagation window).
Give each pipeline its own key, set an expires_at, and rotate on a schedule. See Automate with management keys.

​
7. Minimize what your logs retain

In production, prefer a privacy mode of metadata or none so prompt and response content is never stored — you keep the operational metrics without holding sensitive text. Provider secrets and key-shaped strings are redacted from logs everywhere regardless of mode. See Privacy & compliance.

Authentication & API keys

The six credentials and how each is enforced.

Client tokens

Safe, short-lived credentials for apps.

Rotate BYOK credentials

Zero-downtime provider-key rotation.

Automate with management keys

Least-privilege control-plane automation.