Skip to content
Console
On this page

Trust policies

A TrustPolicy grants a set of Access principals the right to exchange their grant for a provider credential on one Connection, never wider…

A TrustPolicy grants a set of Access principals the right to exchange their grant for a provider credential on one Connection, never wider than the policy's permissions and repositories.

Service Sylphx Broker · Resource type broker.sylphx.com/TrustPolicy · Name pattern orgs/{org}/trust_policies/{trust_policy} · Shape spec_status

Fields

FieldTypeWhat it is
namestringorgs/{org}/trust_policies/{trust_policy}.
uidstringtpol_<cell><ulid>. Output only.
metaResourceMetaResource metadata.
specTrustPolicySpecDesired state. Required.
statusTrustPolicyStatusObserved state. Output only.

Methods

Every method of the collection, in the registry's order, with the scope it needs. The full request, response and examples are one link away.

MethodCallWhat it does
GETgetGets a trust policy.
GETlistLists an org's trust policies.
POSTcreateCreates a trust policy.
PATCHupdateUpdates a trust policy.
DELETEdeleteDeletes a trust policy.
POSTexchange_tokenExchanges 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.
POSTexchange_read_tokenExchanges the caller's Access grant for a read-only GitHub App installation token. Requires the explicit broker:exchange:read scope on this policy, with the same subject, actor, Connection and repository checks as ExchangeToken. Every resolved permission must be read-only: omitting permissions inherits the policy and is refused if it has writes. The provider's returned permissions must confirm the requested ceiling. Writes one TokenExchange audit record; broker:read cannot issue tokens.
POSTopen_git_hub_pull_requestOpens a pull request as the user authorized by the policy's GitHub user Connection. Credentials remain inside Broker. Requires an exact repository, policy subject and actor, and pull_requests=write. Fork heads are refused.

get

Gets a trust policy.

GET https://api.sylphx.com/v1/orgs/acme/trust_policies/trust-policy · scope broker:read · effect read · Request, response and examples

list

Lists an org's trust policies.

GET https://api.sylphx.com/v1/orgs/acme/trust_policies · scope broker:read · effect read · paginated · Request, response and examples

create

Creates a trust policy.

POST https://api.sylphx.com/v1/orgs/acme/trust_policies · scope broker:admin · effect write · Request, response and examples

update

Updates a trust policy.

PATCH https://api.sylphx.com/v1/orgs/acme/trust_policies/trust-policy · scope broker:admin · effect write · Request, response and examples

delete

Deletes a trust policy.

DELETE https://api.sylphx.com/v1/orgs/acme/trust_policies/trust-policy · scope broker:admin · effect destructive · Request, response and examples

exchange_token

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.

POST https://api.sylphx.com/v1/orgs/acme/trust_policies/trust-policy:exchangeToken · scope broker:exchange · effect write · Request, response and examples

exchange_read_token

Exchanges the caller's Access grant for a read-only GitHub App installation token. Requires the explicit broker:exchange:read scope on this policy, with the same subject, actor, Connection and repository checks as ExchangeToken. Every resolved permission must be read-only: omitting permissions inherits the policy and is refused if it has writes. The provider's returned permissions must confirm the requested ceiling. Writes one TokenExchange audit record; broker:read cannot issue tokens.

POST https://api.sylphx.com/v1/orgs/acme/trust_policies/trust-policy:exchangeReadToken · scope broker:exchange:read · effect write · Request, response and examples

open_git_hub_pull_request

Opens a pull request as the user authorized by the policy's GitHub user Connection. Credentials remain inside Broker. Requires an exact repository, policy subject and actor, and pull_requests=write. Fork heads are refused.

POST https://api.sylphx.com/v1/orgs/acme/trust_policies/trust-policy:openGitHubPullRequest · scope broker:github:pull_requests:create · effect write · Request, response and examples