Skip to content
Console
On this page

Exchange token on a trust policy

Exchanges the caller's Access grant for a short-lived provider credential under a trust policy (RFC 8693 token exchange): a GitHub App…

Exchanges the caller's Access grant for a short-lived provider credential under a trust policy (RFC 8693 token exchange): a GitHub App installation token for exactly one of the policy's repositories, narrowed to the requested permissions. The grant's principal (for a delegated grant, its accountable principal) must be a policy subject, its actor must match the policy's actors, and it must hold broker:exchange on this policy. Every call writes one TokenExchange record. A permission the Connection lacks is PERMISSION_DENIED with reason CapabilityMissing, never an outage.

  • 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

Request

FieldTypeWhat it is
namestringThe trust policy to exchange under. Required.
permissionsmap<string, string>The permissions this call needs, at most the policy's; empty means the policy's.
repositoriesstring[]The one repository this call needs, owner/name, one of the policy's; leave empty for non-repository Connections such as OAuth 2.0.
ttldurationHow long the credential should live, at most the policy's max_ttl. A GitHub installation token always lives one hour: unset or 3600s.

Response

FieldTypeWhat it is
tokenstringThe provider credential. Never logged, persisted, or cached by the caller beyond expire_time. Never returned again.
credential_kindCredentialKindWhat token is. One of access_token, runner_registration, vapid_assertion.
expire_timetimestampWhen the credential stops working.
permissionsmap<string, string>The permissions the credential carries.
repositoriesstring[]The one repository the credential covers.
token_exchangestringThe record of this credential, orgs/{org}/trust_policies/{trust_policy}/token_exchanges/{token_exchange}: the name to revoke it by.
connectionstringThe Connection the credential was issued on, the policy's.
issuerstringThe provider identity that signed the credential: for GitHub, github-apps/{app_id} of the installation it was minted against.

Errors

  • UNAUTHENTICATED — No valid key or token was presented.
  • PERMISSION_DENIED — The key lacks the method's permission.
  • RESOURCE_NOT_FOUND — The named Resource does not exist or is not visible.
  • INVALID_FIELD — A field failed validation.
  • INVALID_STATE — The Resource is in a state that forbids the call.
  • RATE_LIMITED — The rate limit is reached; see Retry-After.
  • UNAVAILABLE — The Resource store, the owning service's backend, or the key verifier's snapshot is unavailable; retry after Retry-After.

Every error arrives in the body Errors describes.

Examples

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 '{}'