# Subscription credentials (/guides/subscriptions)



If your team already pays for a **Claude Code** (Anthropic) or **ChatGPT Codex** (OpenAI)
subscription, you can attach it to a Zumik project and serve matching traffic from the allowance
you already bought - instead of paying metered API rates a second time. Eligible requests route to
the subscription's backend at the provider's cache-discounted effective price.

This is part of the BYOK family: Zumik **never stores the raw token**. It is fingerprinted on the
way in and discarded; only the fingerprint, the provider, and the plan label are retained so you
can recognize which credential is configured.

## Attach a subscription [#attach-a-subscription]

<CodeGroup>
  ```bash title="cURL"
  curl https://api.zumik.ai/v2/subscription-credentials \
    -H "Authorization: Bearer $ZUMIK_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "provider": "claude_code",
      "plan": "claude_max",
      "token": "<your-subscription-oauth-token>"
    }'
  ```

  ```json title="Response"
  {
    "id": "sub_01jy...",
    "object": "subscription_credential",
    "provider": "claude_code",
    "plan": "claude_max",
    "status": "active",
    "token_fingerprint": "zsub_4ab2e9c1d0f3a5b7",
    "cached_price_discount_pct": 90,
    "created_at": "2026-06-12T20:15:00Z"
  }
  ```
</CodeGroup>

`provider` is one of:

| Value         | Subscription             | Routes provider | Cached input discount |
| ------------- | ------------------------ | --------------- | --------------------- |
| `claude_code` | Claude Code (Pro/Max)    | `anthropic`     | 90%                   |
| `codex`       | ChatGPT Codex (Plus/Pro) | `openai`        | 50%                   |

## How routing works [#how-routing-works]

On every request, the Execution Broker resolves your model to a provider. If the project has an
**active** subscription whose underlying provider matches, the request is served through that
subscription instead of the metered managed-provider path. You can see which path served a request
on the response:

* On `/v1` (OpenAI-compatible), the proprietary signal rides on headers so the body stays exactly
  OpenAI-shaped:

  ```http
  Agent-Execution-Profile: subscription
  Agent-Subscription-Id: sub_01jy...
  Agent-Subscription-Discount-Pct: 90
  ```

  The discounted input fraction is also reflected in `usage.prompt_tokens_details.cached_tokens`,
  so reuse stays measurable with a vanilla OpenAI SDK.

* On `/v2` (native), the chosen profile is a first-class field:

  ```json
  { "execution_profile": "subscription", "...": "..." }
  ```

## List and revoke [#list-and-revoke]

```bash
# List the project's subscriptions (tokens are never returned, only fingerprints)
curl https://api.zumik.ai/v2/subscription-credentials \
  -H "Authorization: Bearer $ZUMIK_API_KEY"

# Revoke one - matching traffic immediately falls back to the metered path
curl -X DELETE https://api.zumik.ai/v2/subscription-credentials/sub_01jy... \
  -H "Authorization: Bearer $ZUMIK_API_KEY"
```

Every attach and revoke is written to the project audit log
(`subscription.credential.create`, `subscription.credential.revoke`).

## Notes and limits [#notes-and-limits]

* A subscription only serves models that resolve to its underlying provider. A Claude Code
  subscription will not serve an OpenAI model, and vice versa.
* Subscription allowances are governed by the provider's own fair-use terms. Zumik routes through
  the allowance; it does not raise or bypass the provider's limits.
* Billing reflects the cache-discounted input rate for subscription-served requests, so the
  savings appear directly in your reuse credit (see [Billing and budgets](/guides/billing-budgets)).