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
| Field | Type | What it is |
|---|---|---|
name | string | orgs/{org}/trust_policies/{trust_policy}. |
uid | string | tpol_<cell><ulid>. Output only. |
meta | ResourceMeta | Resource metadata. |
spec | TrustPolicySpec | Desired state. Required. |
status | TrustPolicyStatus | Observed 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.
| Method | Call | What it does |
|---|---|---|
GET | get | Gets a trust policy. |
GET | list | Lists an org's trust policies. |
POST | create | Creates a trust policy. |
PATCH | update | Updates a trust policy. |
DELETE | delete | Deletes a trust policy. |
POST | 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 | 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 | 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. |
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