Already using OpenAI directly? This guide will show the smallest set of changes needed to route your traffic through Roadie and gain per-user limits, budgets, and logs. Roadie exposes an OpenAI-compatible surface, so the official OpenAI SDKs keep working with two overrides. The OpenAI drop-in quickstart covers a fresh setup end to end; this guide is the migration checklist for an existing codebase — how to cut over safely, what maps one-to-one, and the handful of differences to check.

​
1. Cut over behind an environment flag

The two things that change are the base URL and the API key. Keep both in the environment so you can flip back to OpenAI instantly if you need to.
  1. Base URL → /openai/v1
  2. API key → your Roadie secret key (rd_sk_…), created in the dashboard
Node
Nothing else in your call sites changes — chat.completions, embeddings, images, streaming, tools, JSON mode, and vision all work verbatim. See Using OpenAI SDKs for the full per-language compatibility matrix.
A secret key grants full access to your project’s data plane. Keep it server-side — never ship it in a browser or mobile app. Client apps mint short-lived client tokens against this same surface. A publishable key (rd_pk_…) is mint-only and returns 403 on model endpoints.

​
2. Add a provider credential (BYOK)

Roadie is bring-your-own-key: the gateway calls OpenAI using your OpenAI key, held server-side. Before your first request succeeds, add that key as a provider credential to the project’s environment in the dashboard. It is validated live on save and envelope-encrypted — only the gateway can ever decrypt it. If a request resolves to a provider with no configured credential, it fails before any provider work with provider_credential_missing. Add an Anthropic key too if you plan to route to anthropic/* models.

​
3. Keep or qualify your model names

The model field accepts three forms, so your existing gpt-4o strings keep working:
  • A bare OpenAI name (gpt-4o) resolves to openai/gpt-4o when it is in your project’s catalog — OpenAI is the default provider on this surface.
  • A qualified provider/model id (anthropic/claude-sonnet-5) routes to that provider directly — this is how you reach Anthropic through the OpenAI SDK.
  • A project alias (smart) that can fail over across providers. See Models, aliases & fallback.
A bare name that matches models from more than one provider is rejected with model_ambiguous (400). Use the qualified provider/model id to disambiguate.

​
4. Review the differences

Almost everything maps one-to-one. These are the edges worth checking during a migration:

​
5. Map error handling

Errors come back in the OpenAI error shape, so your existing try/catch and the OpenAI SDK’s typed error classes keep working. Two Roadie-specific mappings to know:
  • A quota or budget rejection is reported as insufficient_quota at HTTP 429 on this surface, because the OpenAI error schema has no 402. (The native Roadie surface keeps them distinct — quota_error at 429, budget_error at 402.)
  • Provider failures surface only after the gateway exhausts its own retries and fallbacks, mapped to a safe message — never the provider’s raw body.
See the error reference for the full catalog.

​
6. Verify, then keep what you gained

Send a request, then open the dashboard: you now have request logs, usage and cost rollups, and can attach per-end-user limits, quotas, and budgets — all without changing your inference code. To roll back at any point, point baseURL and the API key back at OpenAI. You are never locked in.

​
Next steps

Set usage controls

Cap spend and per-user usage before it happens.

Observability: logs & usage

Inspect request logs, cost, and usage.

Rotate BYOK credentials

Rotate your OpenAI and Anthropic keys with zero downtime.

Using OpenAI SDKs

The full compatibility reference across Node, Python, and Swift.