--- title: "Attenuate token" method: POST path: "/api/v1/tokens/attenuate" tags: ["tokens"] --- # Attenuate token `POST /api/v1/tokens/attenuate` ## Request - Base URL: `https://devs.adaptyvbio.com` - URL: `https://devs.adaptyvbio.com/api/v1/tokens/attenuate` - Auth: HTTP bearer Add restrictions to an existing token without needing the private key. Attenuation is a Biscuit cryptographic feature that allows anyone holding a token to add restriction blocks. The resulting token can only do a subset of what the original token could do—restrictions cannot be removed. # Security Model This endpoint requires the `token:read` capability. 1. **Cryptographic guarantee**: Attenuation can only *reduce* permissions, never expand them. The Biscuit format ensures restriction blocks are append-only and cannot be removed without invalidating the signature. 2. **Self-service by design**: Users can only attenuate tokens they already possess. If you have a token, you can create a weaker version of it—this is analogous to being able to share read-only access to something you own. 3. **No privilege escalation**: The attenuated token inherits all existing restrictions from the source token, plus any new ones added. A read-only token cannot be attenuated into a read-write token. # Use Cases - Create a read-only version of your token for delegation - Restrict a token to specific resources or actions - Generate time-limited tokens for external services - Scope a broad token down to a single organization or project # Timezone All timestamps use UTC in ISO 8601 / RFC 3339 format. # Further Reading For the cryptographic properties of token attenuation, see the [Biscuit documentation](https://doc.biscuitsec.org/). ## Request body - AttenuateTokenRequest: Request to attenuate (restrict) an existing token. Attenuation is a Biscuit cryptographic feature that adds restriction blocks without needing the private signing key. Any authenticated user can attenuate their tokens to create limited-scope versions for delegation. - `attenuated_parent_token_id` string, uuid, nullable: If attenuating an already-attenuated token (chained attenuation), provide the `id` of the parent attenuated token record. Omit when attenuating a root token directly. - `attenuation` AttenuationSpec, required: Restriction options for token attenuation. Create limited-scope versions of your token for delegation or integration with external services. All restrictions are additive—the resulting token can only perform a subset of what the original could do. # Quick Options For common use cases, use the convenience flags: - `read_only: true` — Restrict to read operations only (list, read) - `non_destructive: true` — Allow all operations except delete # Fine-Grained Control For precise control, use explicit whitelists: - `allowed_actions` — Permit only specific operations - `allowed_resources` — Permit only specific resource types # Timezone All timestamps use UTC in ISO 8601 / RFC 3339 format. # Examples **Read-only delegation** for a reporting dashboard: ```json { "token": "abs0_FLOWBIO1...", "attenuation": { "read_only": true } } ``` **Time-limited token** expiring in 1 hour: ```json { "token": "abs0_FLOWBIO1...", "attenuation": { "expires_at": "2026-01-20T13:00:00Z" } } ``` **Restrict to specific actions and resources**: ```json { "token": "abs0_FLOWBIO1...", "attenuation": { "allowed_actions": ["list", "read"], "allowed_resources": ["experiment", "result"] } } ``` **Combine multiple restrictions** (read-only, time-limited, org-scoped): ```json { "token": "abs0_FLOWBIO1...", "attenuation": { "read_only": true, "expires_at": "2026-01-21T00:00:00Z", "allowed_org_ids": ["56a01500-1f17-4908-a6a8-472e349e5733"] } } ``` # Further Reading For details on the cryptographic properties of token attenuation, see the [Biscuit documentation](https://doc.biscuitsec.org/). - `allowed_actions` string[], nullable: Explicit list of permitted operations. Values: `list`, `read`, `create`, `update`, `delete`, `issue`, `revoke`, `mint_token` If specified, only these operations are allowed. Applied alongside `read_only` and `non_destructive`; effective permissions are the intersection of all constraints. - `allowed_org_ids` string[], nullable: Restrict token to only these organization IDs. The token must already have access to these orgs; attenuation cannot expand access. The token's append-only property enforces this cryptographically. - `allowed_resources` string[], nullable: Explicit list of permitted resource types. Common values: `experiment`, `sequence`, `target`, `result`, `project`, `organization`, `user`, `token`, `webhook`, `update`, `quote`, `invoice`, `billing`, `feedback`, `partner`, `credit`, `usage`, `product`, `info`, `admin`, `policy` If specified, the token can only access these resource types. - `expires_at` string, date-time, nullable: Shorten token expiration to this timestamp (cannot extend past original expiry). Format: ISO 8601 / RFC 3339 (e.g., "2026-01-20T00:00:00Z") - `non_destructive` boolean: Allow all operations except destructive ones (delete). When enabled, the token can list, read, create, and update but not delete. - `payment_policy` string[], nullable: Restrict which payment rails the token may be offered. Values: `invoice`, `machine`, `both` — each naming a rail set the attenuation permits. Multiple entries are the sets `query_all` unions across the block; the extractor intersects their bounds, so the effective policy is the authority block's rail set intersected with what these permit. Like every other field here this only narrows. A token issued for the legacy invoice flow cannot attenuate itself into machine payment: the capability lives in the token's sealed authority block, and an appended block can only intersect with it. Restricting a `machine` or `both` token to `invoice` is the useful direction — it hands a delegate a token that can read and act but never open a machine-payment session. - `read_only` boolean: Restrict to list and read operations only. When enabled, the token cannot create, update, or delete resources. - `name` string, required: Human-readable label for this attenuated token. Names are not unique — they are purely for display purposes. - `token` string, required: Existing token string (format: `abs0_{slug}{biscuit_base64}`) to attenuate. ## Response `201` Token attenuated and persisted - AttenuateTokenResponse: Response after attenuating a token. - `id` string, required: Database ID of the attenuated token record (for revocation/management). - `token` string, required: The attenuated token string. Format: `abs0_{slug}{biscuit_base64}`. ## Other responses - `400`: Invalid token format or attenuation spec - `401`: Invalid or missing authentication token - `403`: Insufficient permissions --- [API](https://skmtc.dev/adaptyvbio/apis/adaptyv-foundry-api.md) - [All operations](https://skmtc.dev/adaptyvbio/apis/adaptyv-foundry-api/llms.txt) - [OpenAPI document](https://skmtc.dev/adaptyvbio/apis/adaptyv-foundry-api/revisions/5a2228f4bd59?raw)