# Subscription credentials (/api-v2/subscription-credentials)



Many teams already pay for a Claude Code (Anthropic) or ChatGPT Codex (OpenAI) subscription with a generous monthly allowance. Attaching that subscription routes eligible traffic for the underlying provider through the subscription's OAuth backend, using the allowance you already bought at the provider's cache-discounted effective price. Credential ids are prefixed `sub_`. See the [subscriptions guide](/guides/subscriptions).

Like BYOK, the raw OAuth or session token is fingerprinted on the way in and discarded. Only the fingerprint, the provider, and the plan label are retained.

All requests require a bearer API key. See [authentication](/api-reference/authentication).

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

`POST /v2/subscription-credentials`

<ParamField body="provider" type="string">
  One of `claude_code` (routes to `anthropic`) or `codex` (routes to `openai`).
</ParamField>

<ParamField body="token" type="string">
  The raw OAuth or session token from the subscription. Must not be empty. Fingerprinted and discarded; never stored or logged.
</ParamField>

<ParamField body="plan" type="string">
  A free-form plan label, e.g. `claude_max` or `chatgpt_pro`. Defaults to the provider's label.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary JSON you attach for your own bookkeeping.
</ParamField>

```bash
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": "oauth-..."
  }'
```

```json
{
  "id": "sub_01jy7nop78r0s1t2u3v4w5x6yz",
  "object": "subscription_credential",
  "project_id": "prj_01jy7n0a4c8m2t6v9q3wrxk7bd",
  "provider": "claude_code",
  "plan": "claude_max",
  "status": "active",
  "token_fingerprint": "zsub_7c2b9e1a4d6f8302",
  "cached_price_discount_pct": 90,
  "created_at": "2026-06-15T16:33:20Z",
  "metadata": {}
}
```

<ResponseField name="id" type="string">
  Opaque credential id, prefixed `sub_`.
</ResponseField>

<ResponseField name="object" type="string">
  Always `subscription_credential`.
</ResponseField>

<ResponseField name="project_id" type="string">
  The owning project.
</ResponseField>

<ResponseField name="provider" type="string">
  `claude_code` or `codex`.
</ResponseField>

<ResponseField name="plan" type="string">
  The plan label.
</ResponseField>

<ResponseField name="status" type="string">
  `active`, `disabled`, or `revoked`.
</ResponseField>

<ResponseField name="token_fingerprint" type="string">
  A non-reversible fingerprint of the token, prefixed `zsub_`.
</ResponseField>

<ResponseField name="cached_price_discount_pct" type="integer">
  The effective input-token discount this subscription unlocks: 90 for Claude Code, 50 for Codex.
</ResponseField>

<ResponseField name="created_at" type="string">
  RFC 3339 creation timestamp.
</ResponseField>

<ResponseField name="metadata" type="object">
  The metadata you supplied.
</ResponseField>

## List subscriptions [#list-subscriptions]

`GET /v2/subscription-credentials`

```bash
curl https://api.zumik.ai/v2/subscription-credentials \
  -H "Authorization: Bearer $ZUMIK_API_KEY"
```

```json
{
  "object": "list",
  "data": [
    {
      "id": "sub_01jy7nop78r0s1t2u3v4w5x6yz",
      "object": "subscription_credential",
      "provider": "claude_code",
      "plan": "claude_max",
      "status": "active",
      "cached_price_discount_pct": 90
    }
  ]
}
```

## Delete a subscription [#delete-a-subscription]

`DELETE /v2/subscription-credentials/{credential_id}`

<ParamField path="credential_id" type="string">
  The `sub_...` id to delete.
</ParamField>

```bash
curl -X DELETE https://api.zumik.ai/v2/subscription-credentials/sub_01jy7nop78r0s1t2u3v4w5x6yz \
  -H "Authorization: Bearer $ZUMIK_API_KEY"
```

```json
{
  "id": "sub_01jy7nop78r0s1t2u3v4w5x6yz",
  "object": "subscription_credential.deleted",
  "deleted": true
}
```

## Errors [#errors]

| Status | Code                    | When                                           |
| ------ | ----------------------- | ---------------------------------------------- |
| 400    | `invalid_request_error` | `token` is empty.                              |
| 401    | `invalid_api_key`       | Missing or invalid API key.                    |
| 404    | `invalid_request_error` | The credential does not exist in this project. |

See the full table on [errors](/api-reference/errors).