> ## Documentation Index
> Fetch the complete documentation index at: https://www.aptible.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Upgrading from v1.0
> What changed between LLM Gateway v1.0 and v2.0, and how to migrate your existing keys and integrations.
## Overview
LLM Gateway v2.0 introduces:
* **Significant performance improvements**, with responses up to 5x times faster
* **Automatic provider fail over** via a new, provider-agnostic model naming scheme, allowing the gateway to automatically fail over between providers without any client-side changes
* **Longer log retention** with 90 days of logs now available in the dashboard and 6+ years retained for audit purposes
* **Simplified scoping** for LLM Keys, model access policies, and spend limits by shifting them from being scoped per Environment to being scoped to your whole organization.
* A **new base url** in order to facilitate ease of migration from v1.0
Any LLM Key you created before v2.0 keeps working exactly as it did under v1.0, with the old base URL and model names. These keys will NOT be disabled or automatically migrated, and will appear under **Legacy Keys** in [LLM Gateway](https://app.aptible.com/llm-gateway). Any key you create going forward is a v2.0 key by default.
v1.0 and v2.0 keys work side by side. You can migrate one application or agent at a time, verify it, and move on to the next, rather than cutting everything over at once.
## What changed
| Area | v1.0 | v2.0 |
| - | - | - |
| Base URL | `https://llm-gateway-api.aptible.com` | `https://llm-gateway.aptible.com`
With optional `/openai`, `/anthropic`, and `/harness/` paths — see [Supported APIs](/docs/llm-gateway/supported-apis) |
| Model names | Provider-prefixed, e.g. `bedrock/us.anthropic.claude-sonnet-5` | Provider-agnostic, e.g. `claude-sonnet-5` — see [Supported Models](/docs/llm-gateway/supported-models) |
| LLM Keys | Scoped to an Environment | Scoped to your organization — see [LLM Keys](/docs/llm-gateway/llm-keys) |
| Model access policy | Configured per Environment | One policy for your whole organization — see [Model Access Policies](/docs/llm-gateway/model-access-policies) |
| Spend limit & tracking | Org-wide limit, tracked at the org, environment, and key level | Org-wide limit, tracked at the org and key level (environment level removed) — see [Cost Visibility & Control](/docs/llm-gateway/cost-control) |
| Log retention | 7 days in the dashboard, with an optional Langfuse drain for longer retention | 90 days in the dashboard, 6+ years retained by Aptible for audit purposes. Langfuse drains no longer supported. — see [Audit Logging](/docs/llm-gateway/audit-logging) |
| Provider failover | Not available | Automatic failover to another provider if a model's primary provider has an outage |
Model access policies and spend limits used to apply per Environment. If you had different allowed models or limits across multiple Environments, moving your last v1.0 key to v2.0 collapses them into a single organization-wide policy and limit. Check your organization's combined [model access policy](/docs/llm-gateway/model-access-policies) and [spend limit](/docs/llm-gateway/cost-control) before you do, so you don't lose access to a model or land on a lower limit than you expect.
## Migrate a key
For each key you created before v2.0:
Go to [LLM Gateway](https://app.aptible.com/llm-gateway) and select **Create Key**. Unlike v1.0, you don't need to create an Environment first — the new key is scoped to your organization. See [Creating a Key](/docs/llm-gateway/llm-keys#creating-a-key) for details.
In the app, agent, or harness configuration where you use the old key, change the base URL to `https://llm-gateway.aptible.com`, or to a strict-compatibility namespace like `https://llm-gateway.aptible.com/openai` or `https://llm-gateway.aptible.com/anthropic`. If you're configuring a supported coding assistant or agent harness, use its dedicated `/harness/` base URL instead — see [Supported APIs](/docs/llm-gateway/supported-apis) for the full list.
Then update the configured model name(s) to the new IDs from [Supported Models](/docs/llm-gateway/supported-models):
```jsonc theme={null}
{
// Before (v1.0)
"model": "bedrock/us.anthropic.claude-sonnet-5"
// After (v2.0)
"model": "claude-sonnet-5"
}
```
Replace the old key with the new one in that same configuration, then redeploy or restart as needed.
Confirm requests are flowing by checking the new key's request history in [LLM Gateway](https://app.aptible.com/llm-gateway). Once you're confident the migration is complete, revoke the old key — see [Revoking a Key](/docs/llm-gateway/llm-keys#revoking-a-key).
If you drained logs to Langfuse under v1.0, note that Langfuse draining isn't available for v2.0 keys. Aptible now retains every log automatically for 6+ years, so a drain isn't needed for long-term retention, but if you built dashboards or alerting on top of that export, you'll need to replace it with [Audit Logging](/docs/llm-gateway/audit-logging), or [contact Aptible Support](https://app.aptible.com/support) about other export options.
## Troubleshooting
Yes, but not immediately. A v1.0 key keeps working with v1.0's original base URL and model names, and it will continue to show as a Legacy Key in [LLM Gateway](https://app.aptible.com/llm-gateway). But v2.0-only features like automatic provider failover are only available with a v2.0 key. The sooner you switch, the sooner you have access to these and other upcoming improvements.
Once the majority of Aptible customers have migrated to v2.0 keys, we will set an EOL date for making requests with v1.0 keys.
Double-check that you updated the model name, not just the base URL. v1.0's provider-prefixed names (e.g. `bedrock/us.anthropic.claude-sonnet-5`) aren't recognized against the v2.0 base URL. Use the plain ID from [Supported Models](/docs/llm-gateway/supported-models) (e.g. `claude-sonnet-5`) instead.
A v1.0 key won't authenticate against the v2.0 base URL, and a v2.0 key won't authenticate against the v1.0 base URL. Make sure the key and base URL you're using are from the same version.
This can happen if your v1.0 Environments had different model access policies and the model you need was only allowed in one of them. Ask an Account Owner to review and update your organization's single [Model Access Policy](/docs/llm-gateway/model-access-policies).