---
# @generated by sylphx-gen 0.1.0 from contracts@e145cc7cf1bc9605f2b27439e5e17ed76a1a2fd7e7021906a013f7565e4a0cd5. Do not edit.
title: "Exchange token on a trust policy"
description: "`broker.trust_policies.exchange_token` (POST /v1/{name}:exchangeToken): Exchanges the caller's workload identity for a short-lived provider credential under a trust policy (RFC 8693 token exchange)."
type: reference
product: platform
summary: "Exchanges the caller's workload identity for a short-lived provider credential under a trust policy (RFC 8693 token exchange)."
updated: 2026-09-28
nav: false
---

> **This method is not served on the public API.** `api.sylphx.com` does not route this call: its backend is not deployed behind the public API, or does not implement the call. This page documents the contract. It is kept out of the sidebar and of search engines.

Exchanges the caller's workload identity for a short-lived provider credential under a trust policy (RFC 8693 token exchange). The credential is narrowed to the request and cached per installation and permission set; a permission the Connection lacks is PERMISSION_DENIED with reason `CapabilityMissing`, never an outage.

**Not available yet.** Sylphx Broker is declared in the registry but no backend serves it: every call answers `501` with the problem code `UNIMPLEMENTED`.

- **Path** `POST https://api.sylphx.com/v1/orgs/acme/trust_policies/trust-policy:exchangeToken`
- **Scope** `broker:exchange`
- **Effect** `write` — a successful call changes state.
- **Collection** [trust_policies](/docs/api/trust_policies)

## Request

| Field | Type | What it is |
| --- | --- | --- |
| `name` | `string` | The trust policy to exchange under. Required. |
| `subject_token` | `string` | The caller's identity: a SPIFFE JWT-SVID or an Access-issued workload OIDC token, with audience `broker.sylphx.com`. Required. Never returned again. |
| `permissions` | `map<string, string>` | The permissions this call needs, at most the policy's; empty means the policy's. |
| `repositories` | `string[]` | The repositories this call needs, at most the policy's; empty means the policy's. |
| `ttl` | `duration` | How long the credential should live, at most the policy's `max_ttl`. |

## Response

| Field | Type | What it is |
| --- | --- | --- |
| `token` | `string` | The provider credential. Never logged, persisted, or cached by the caller beyond `expire_time`. Never returned again. |
| `credential_kind` | `CredentialKind` | What `token` is. One of `access_token`, `runner_registration`. |
| `expire_time` | `timestamp` | When the credential stops working. |
| `permissions` | `map<string, string>` | The permissions the credential carries. |
| `repositories` | `string[]` | The repositories the credential covers; empty means every repository the Connection covers. |

## Errors

- [`UNAUTHENTICATED`](/docs/api/errors/UNAUTHENTICATED) — No valid key or token was presented.
- [`PERMISSION_DENIED`](/docs/api/errors/PERMISSION_DENIED) — The key lacks the method's permission.
- [`RESOURCE_NOT_FOUND`](/docs/api/errors/RESOURCE_NOT_FOUND) — The named Resource does not exist or is not visible.
- [`INVALID_FIELD`](/docs/api/errors/INVALID_FIELD) — A field failed validation.
- [`INVALID_STATE`](/docs/api/errors/INVALID_STATE) — The Resource is in a state that forbids the call.
- [`RATE_LIMITED`](/docs/api/errors/RATE_LIMITED) — The rate limit is reached; see Retry-After.

Every error arrives in the body [Errors](/docs/platform/errors) describes.

## Examples

**cURL**

```curl
curl -X POST "https://api.sylphx.com/v1/orgs/acme/trust_policies/trust-policy:exchangeToken" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject_token":"…"}'
```

**TypeScript**

```ts
const response = await sylphx.broker.trustPolicies.exchangeToken({ name: 'orgs/acme/trust_policies/trust-policy', subjectToken: '…' })
```

**Rust**

```rust
let mut req = sylphx::broker::ExchangeTokenRequest::default();
req.name = "orgs/acme/trust_policies/trust-policy".to_string();
req.subject_token = "…".to_string();
let response = sx.broker().trust_policies().exchange_token(req).await?;
```

**CLI**

```bash
sylphx broker trust-policies exchange-token orgs/acme/trust_policies/trust-policy
```

**MCP**

```json
{ "method_id": "broker.trust_policies.exchange_token", "args": {"name":"orgs/acme/trust_policies/trust-policy","subject_token":"…"} }
```