---
title: "Set Subscription Token"
method: PUT
path: "/secrets/{secret_id}/subscription-token"
tags: ["Secrets"]
---

# Set Subscription Token

`PUT /secrets/{secret_id}/subscription-token`

## Request

- Base URL: `/api` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/secrets/{secret_id}/subscription-token`
- Auth: API key in header `Authorization`

## Path parameters

- `secret_id` string, uuid, required

## Request body

- SubscriptionTokenRequest: A token pasted from `claude setup-token`.
  - `token` string, required

## Response `200`

Successful Response

- PublicSecretResponseDTO: Caller-facing representation after grant-aware value projection.
  - `slug` string, nullable
  - `id` string, uuid, nullable
  - `kind` 'provider_key' | 'custom_provider' | 'sso_provider' | 'webhook_provider' | 'custom_secret' | 'channel_secret' | 'subscription_provider' | 'oauth_provider' | 'oauth_grant', required
  - `data` union, required
    - StandardProviderDTO
      - `kind` 'mock' | 'openai' | 'cohere' | 'anyscale' | 'deepinfra' | 'alephalpha' | 'groq' | 'minimax' | 'mistral' | 'mistralai' | 'anthropic' | 'perplexityai' | 'together_ai' | 'openrouter' | 'gemini' | 'xai', required
      - `provider` StandardProviderSettingsDTO, required
        - `key` string, nullable
      - `models` CustomModelSettingsDTO[], nullable
        - `slug` string, required
        - `extras` object, nullable
      - `harnesses` string[], nullable
    - MCPStandardProviderDTO
      - `kind` 'mock' | 'composio', required
      - `provider` StandardProviderSettingsDTO, required
        - `key` string, nullable
    - CustomProviderDTO
      - `kind` 'custom' | 'azure' | 'bedrock' | 'sagemaker' | 'vertex_ai' | 'openai' | 'cohere' | 'anyscale' | 'deepinfra' | 'alephalpha' | 'groq' | 'minimax' | 'mistral' | 'mistralai' | 'anthropic' | 'perplexityai' | 'together_ai' | 'openrouter' | 'gemini' | 'xai', required
      - `provider` CustomProviderSettingsDTO, required
        - `url` string, nullable
        - `version` string, nullable
        - `key` string, nullable
        - `extras` object, nullable
      - `models` CustomModelSettingsDTO[], required
        - `slug` string, required
        - `extras` object, nullable
      - `harnesses` string[], nullable
      - `protocol` 'openai' | 'anthropic': The provider family a custom endpoint speaks, i.e. its request/response shape. Chat-completions vs responses is deliberately absent: the relay serves `/v1/chat/completions`, `/v1/responses` and `/v1/messages` on every custom endpoint and the harness picks the suffix. Only openai-vs-anthropic changes behaviour. A record written before this field existed has no value and is read as OpenAI-compatible.
      - `provider_slug` string, nullable
      - `model_keys` string[], nullable
    - SSOProviderDTO
      - `provider` SSOProviderSettingsDTO, required
        - `client_id` string, required
        - `client_secret` string, nullable
        - `issuer_url` string, required
        - `scopes` string[], required
        - `extra` object
    - WebhookProviderDTO
      - `provider` WebhookProviderSettingsDTO, required
        - `key` string, nullable
    - CustomSecretDTO
      - `secret` CustomSecretSettingsDTO, required
        - `format` 'text' | 'json', required
        - `default_env_var` string, nullable
        - `content` union
          - string
          - object
    - ChannelSecretDTO
      - `kind` 'slack' | 'telegram' | 'whatsapp' | 'agenta' | 'bridge', required
      - `channel` ChannelSecretSettingsDTO, required: Vault-stored credential fields only -- things a platform issued and we verify. A bridge's `delivery_url` is not a credential (it is our own address to call, not who is calling us) and does not belong here: it lives on `ChannelConnectionCreate.data`. Unknown keys passed here are silently dropped, so routing a non-credential field through this shape would vanish with no error.
        - `bot_token` string, nullable
        - `signing_secret` string, nullable
        - `webhook_secret` string, nullable
        - `access_token` string, nullable
        - `app_secret` string, nullable
    - OAuthProviderDTO
      - `provider` OAuthProviderSettingsDTO, required
        - `client_id` string, required
        - `client_secret` string, nullable
        - `issuer_url` string, required
        - `scopes` string[], required
        - `extra` object
    - OAuthGrantDTO
      - `grant` OAuthGrantSettingsDTO, required
        - `server` string, required
        - `access_token` string, nullable
        - `refresh_token` string, nullable
        - `expires_at` integer, nullable
        - `scopes` string[], required
        - `issuer` string, nullable
        - `endpoint_id` string, uuid, nullable
        - `client_registration_slug` string, nullable
        - `client_id` string, nullable
    - SubscriptionProviderDTO
      - `provider` 'chatgpt' | 'claude': The product family behind a hosted subscription connection.
      - `harnesses` string[], nullable
      - `models` string[], nullable
      - `login` SubscriptionLoginDTO: A harness-format subscription credential, stored and returned verbatim. The shape is Pi's, not ours: extra keys are kept so a Pi version that adds a field round-trips through the vault without losing it.
        - `type` string
        - `access` string, nullable
        - `refresh` string, nullable
        - `expires` integer, nullable
        - `accountId` string, nullable
      - `login_version` integer
      - `login_generation` integer
      - `login_state` 'pending_login' | 'ready' | 'needs_login': How usable the stored subscription login is right now.
      - `login_error` string, nullable
      - `login_attempt` SubscriptionLoginAttemptDTO: The device login this connection waits on, kept on the row. The runner pod that runs the provider poll reports the outcome here, and every poll answers from this record, so neither the browser's poll nor the outcome depends on reaching that same pod again.
        - `id` string, required
        - `expires_at` string, nullable
        - `user_code` string, nullable
        - `verification_uri` string, nullable
        - `poll_after_ms` integer, nullable
        - `state` string
        - `error` string, nullable
        - `runner_address` string, nullable
        - `runner_replica_id` string, nullable
      - `provider_slug` string, nullable
      - `model_keys` string[], nullable
  - `header` Header, required
    - `name` string, nullable
    - `description` string, nullable
  - `lifecycle` LegacyLifecycleDTO
    - `created_at` string, nullable
    - `updated_at` string, nullable
    - `updated_by_id` string, nullable
    - `updated_by` string, nullable
  - `write_only` boolean
  - `management` PublicSecretManagementDTO
    - `policy` 'manager_only', required
  - `value_status` SecretValueStatus, required
    - `configured` boolean, required
    - `preview` string, nullable

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-21** `1d98cd0e4892`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agenta-ai/apis/agenta-api/changes/secrets/:secret_id/subscription-token/put.md)

---

[API](https://skmtc.dev/agenta-ai/apis/agenta-api.md) - [All operations](https://skmtc.dev/agenta-ai/apis/agenta-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agenta-ai/apis/agenta-api/revisions/ab601a2309da?raw)