How to Migrate from Portkey to TrueFoundry

Portkey is a capable AI gateway, and for a team that fits inside its tiers it works well. The difficulty many teams run into is not capability in the abstract, it is where each capability sits in the pricing structure. The thing you need next, SSO, a longer log window, a VPC deployment, PII anonymization, tends to live one tier up from where you are, and the top tier is custom-priced and opaque.

That tiering is what turns a Portkey evaluation into a migration conversation. A team on the Pro plan discovers that SSO is not available at their tier at all, that 30-day log retention is not enough for an incident investigation or a compliance audit, and that running the data plane inside their own VPC requires Enterprise. At that point the question becomes whether to negotiate an opaque enterprise contract for features that should arguably be standard, or to move to a gateway where governance and deployment flexibility are not gated behind the highest tier.

This is a migration guide for teams in that position. It describes Portkey's tiering reality fairly, names the specific reasons teams move, and lays out a step-by-step migration to TrueFoundry that is low-risk because both gateways speak the OpenAI-compatible API. In most cases the client change is a single base URL.

Want SSO, VPC, and deep cost governance without tier cliffs? Book a demo.

Portkey's tiering reality

To plan a migration you need an honest map of what Portkey gives you at which tier, because the whole decision turns on it.

The open-source core does routing only. Portkey's OSS gateway handles routing, fallback, and load balancing. It does not include observability, caching, virtual keys, or RBAC. If you adopted Portkey OSS expecting the full product, you got the request-routing layer and nothing else.

The hosted product adds the operational layer. Logs and traces, virtual keys, caching, and prompt management come with the hosted (managed) product, not the OSS core. This is where most teams actually run Portkey.

Enterprise gates the governance and deployment features. SSO, compliance features, VPC/private tenancy, PII anonymization, and a BAA are Enterprise-only, custom-priced. The capabilities most relevant to a regulated enterprise sit behind the tier with no public price.

The Pro plan's specific caps. The published tiers make the ceiling concrete:

The jump from Pro to Enterprise is not incremental. There is no middle tier where you can buy just SSO or just 90-day retention. The moment you need any Enterprise-gated feature, you are in a custom-pricing negotiation, which is exactly the friction that sends teams to evaluate alternatives.

Why teams migrate to TrueFoundry

The reasons are specific, and they line up with the tiering above.

• SSO, compliance, and VPC without the opaque jump. Teams need identity-provider-backed SSO, SCIM provisioning, audit, and the ability to run the data plane in their own network, and they do not want those table-stakes governance features gated behind a custom enterprise contract.
• Deeper cost governance. Beyond per-key limits, teams want budgets and rate limits per user, team, and model with real cost attribution tagged by team, so FinOps can allocate spend accurately rather than reading an aggregate log.
• Consolidation into one control plane. Rather than a gateway here, observability there, and MCP governance somewhere else, teams want gateway + governance + observability + MCP in a single control plane, with on-prem or air-gapped deployment available, not just VPC on the top tier.
• Retention they control. A fixed 30-day log window is thin for incident forensics and audit. Teams want to set retention to their compliance requirement, not their pricing tier.

TrueFoundry is positioned for exactly this: a unified OpenAI-compatible gateway with routing (latency, weight, priority), fallback with in-request retries, exact and semantic caching, budgets and rate limits per user/team/model, per-request observability with cost attribution, inline guardrails, plus RBAC, SSO, SCIM, and audit, and an MCP gateway, all in one control plane that deploys SaaS, in-VPC, on-prem, or air-gapped with the data plane staying in your network. The governance is not a tier; it is the product. For the general selection framing, see how to choose an AI gateway.

See how TrueFoundry consolidates gateway, governance, and observability in one plane. Book a demo.

The migration path

The migration is incremental and reversible. You do not flip everything at once, and because both gateways speak the OpenAI-compatible API, the client-side change is minimal.

Step 1: Inventory

Catalog what Portkey is doing for you:

• Every config (the routing, fallback, caching, and retry definitions).
• Every virtual key and which app or team uses it, plus its limits.
• Any guardrails configured, and any prompt management assets if you use that feature.
• Provider credentials Portkey holds.
• Your log retention expectation and any compliance requirement it must meet.
• Every caller: the apps, services, and jobs pointing at Portkey's endpoint, and the base URLs they use.

Capture the retention and compliance expectation explicitly. One reason you are migrating is likely that 30 days is not enough, so define the target (say 180 or 365 days) now, as a migration requirement.

Step 2: Map concepts

Translate Portkey concepts to their TrueFoundry equivalents. The capabilities overlap, so this is reframing, not rebuilding.

Step 3: Run both in parallel

This is what makes the migration safe. Portkey and TrueFoundry both expose an OpenAI-compatible API, so the only change a client needs is the base URL. No SDK change, no request-shape rewrite, no response-parsing change.

Stand up TrueFoundry alongside Portkey. Point one low-risk service at the new base URL and verify: responses match, observability shows the traffic with correct cost attribution, budgets and guardrails behave as configured, and caching hits as expected. Because both endpoints are live, you compare them directly and revert a service to Portkey's base URL in seconds if anything is off.

A concrete example: if your service reads its endpoint from OPENAI_API_BASE, migrating that service is changing one environment variable and restarting, and rolling back is changing it back. That is the full client-side blast radius when both gateways speak the same API.

Step 4: Migrate observability and retention expectations

This step is specific to the Portkey migration because retention is often the reason you are moving. Before you cut over production traffic, confirm that TrueFoundry's observability captures what Portkey's logs did, per-request tokens, latency, model, and cost, and that retention is set to your target window rather than a tier-imposed 30 days. Validate that cost attribution tags by team the way FinOps needs, because moving from aggregate hosted logs to team-tagged per-request observability is one of the concrete gains you are migrating for. Our overview of LLM observability tools covers what good per-request observability should include.

Step 5: Cut over by team

Migrate traffic in waves, by team or application:

1. Pick a team. Create their TrueFoundry access, RBAC role, budgets, model-catalog scope, mirroring their old Portkey virtual-key limits.
2. Swap their callers' base URL to TrueFoundry.
3. Watch observability for a defined bake period: cost attribution, latency, error rate, cache hit rate, and guardrail behavior.
4. Move the next team.

Per-team cutover gives a clean rollback boundary and lets you define budgets and access correctly per team as you go, rather than porting a tangle of shared virtual keys in one risky jump.

Step 6: Decommission

Once every caller points at TrueFoundry and has baked long enough to trust, decommission Portkey: stop routing to it, remove provider secrets from its configs, and rotate those provider credentials so the old copies are dead. Confirm no job, notebook, or CI step still points at the old endpoint before you turn it off. The migration is complete when there is one governed path to every model and no orphaned Portkey config holding live keys.

Portkey vs a unified control plane

The structural difference, and the reason the migration is worth it for the teams it suits, is where governance lives.

The point is not that Portkey lacks these features, its Enterprise tier has many of them. The point is that for a team that needs SSO, VPC, and real retention, those are standard in a unified control plane rather than reasons to enter a custom-pricing negotiation. For teams also governing MCP tool access, consolidating that into the same plane is covered in enterprise MCP governance.

Where teams get this wrong

Migrating before defining the retention target. The whole reason many teams leave Portkey is the 30-day log cap, yet they migrate without writing down the retention they actually need. Set the target window as an explicit migration requirement so you validate it during parallel run, not after cutover.

Porting shared virtual keys as-is. Portkey deployments accumulate shared virtual keys. Recreating them one-for-one rebuilds ungoverned access in the new system. Use the cutover to define RBAC per team against your identity provider, which is a core reason you are moving.

Treating the base-URL swap as the migration. The OpenAI-compatible API makes the client change trivial, but the value is the governance: SSO, RBAC, budgets, audit, and retention you control. Swapping URLs without configuring the governance leaves you with a different gateway and the same gaps.

Forgetting to rotate secrets at decommission. If you shut down Portkey but leave the provider keys it held un-rotated, those credentials are live in a decommissioned, unmonitored system. Rotate every credential the old gateway held as part of decommission.

Big-bang cutover. Flipping the whole org at once removes your rollback boundary. Parallel run and team-by-team cutover keep any problem contained to one team and reversible with a single base-URL revert.

Conclusion

Migrating off Portkey is rarely about capability in the abstract; it is about where capability sits in the pricing structure. When SSO, VPC, PII handling, and real log retention all live in a custom-priced Enterprise tier, a team that needs those features faces a choice between an opaque negotiation and a move to a platform where governance and deployment flexibility are standard.

The move itself is low-risk. Both gateways speak the OpenAI-compatible API, so the client change is usually one base URL. Inventory your configs and virtual keys, map them to RBAC, policy, and observability, validate retention during a parallel run, cut over team by team, and decommission with a full secret rotation. Done that way, you consolidate gateway, governance, observability, and MCP into one control plane, deployed in your own network, without a rewrite.

Move from Portkey to a unified control plane. Book a demo.