Skip to content
Console
On this page

Update a trust policy

Updates a trust policy.

Updates a trust policy.

  • Path PATCH https://api.sylphx.com/v1/orgs/acme/trust_policies/trust-policy
  • Scope broker:admin
  • Effect write — a successful call changes state.
  • Collection trust_policies
  • Query update_mask, validate_only

Request

FieldTypeWhat it is
trust_policyTrustPolicyThe trust policy to update; name identifies it. Required.
update_maskfield_maskThe fields to write; unset writes every populated field.
validate_onlyboolValidate and return the result without writing anything.

TrustPolicy

FieldTypeWhat it is
namestringorgs/{org}/trust_policies/{trust_policy}.
metaResourceMetaResource metadata.
specTrustPolicySpecDesired state. Required.

ResourceMeta

FieldTypeWhat it is
labelsmap<string, string>Caller-writable, indexed labels (AIP-122 label rules).
annotationsmap<string, string>Caller-writable, unindexed annotations.
display_namestringCaller-writable human-readable name.

TrustPolicySpec

FieldTypeWhat it is
connectionstringThe Connection credentials are issued on: An active GitHub installation, GitHub user, OAuth 2.0, or Web Push Connection in the same org. Required.
subjectsstring[]The Access principals allowed to exchange, orgs/{org}/principals/{id} in the policy's org: the caller's own principal, or the accountable principal of a delegated grant. 1 to 64. Required.
permissionsmap<string, string>Empty for a VAPID assertion or generic OAuth 2.0 Connection. Otherwise the GitHub permission ceiling, for example {"contents": "write", "pull_requests": "write"}. administration is read only; organization permissions are refused. A policy with actors carries at most contents and pull_requests.
repositoriesstring[]Empty for a VAPID assertion or generic OAuth 2.0 Connection. Otherwise 1 to 1000 exact owner/name entries, no wildcard, each owned by the Connection's account. One exchange covers exactly one repository.
credential_kindCredentialKindWhat Broker issues: access_token or vapid_assertion on the wire. Required. One of access_token, runner_registration, vapid_assertion.
max_ttldurationThe longest a credential lives: GitHub default/maximum 3600s; OAuth 2.0 and VAPID default/maximum 86400s (capped by upstream expiry). Positive whole seconds only for VAPID.
actorsstring[]The Agents a delegated grant may act for: an Agent name orgs/{org}/projects/{project}/envs/{env}/agents/{agent}, or every Agent of an environment, .../envs/{env}/agents/*. 0 to 64. When set, only a delegated grant whose actor matches may exchange; a grant with no actor is refused. When empty, any grant of a subject may exchange, delegated or not.
github_action_budgetGitHubActionBudgetRequired for GitHub user actions. Zero denies actions; ceilings are 80 per minute and 500 per hour. This policy budget does not replace GitHub limits.

GitHubActionBudget

FieldTypeWhat it is
per_minuteint32Maximum admissions in a rolling 60-second window; 1 to 80. Required.
per_hourint32Maximum admissions in a rolling 3600-second window; 1 to 500. Required.

Response

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

ResourceMeta

FieldTypeWhat it is
generationint64Increases by one on every change to spec. Output only.
etagstringStrong ETag (AIP-154): changes on any change to spec, status, or metadata. Send it back as If-Match or etag to make Update and Delete conditional; a mismatch fails with ABORTED / 409 ETAG_MISMATCH. Output only.
create_timetimestampWhen the Resource was created. Output only.
update_timetimestampWhen the Resource last changed. Output only.
delete_timetimestampSet while the Resource is being deleted. Output only.
labelsmap<string, string>Caller-writable, indexed labels (AIP-122 label rules).
annotationsmap<string, string>Caller-writable, unindexed annotations.
display_namestringCaller-writable human-readable name.
creatorstringThe principal that created the Resource. Output only.

TrustPolicySpec

FieldTypeWhat it is
connectionstringThe Connection credentials are issued on: An active GitHub installation, GitHub user, OAuth 2.0, or Web Push Connection in the same org. Required.
subjectsstring[]The Access principals allowed to exchange, orgs/{org}/principals/{id} in the policy's org: the caller's own principal, or the accountable principal of a delegated grant. 1 to 64. Required.
permissionsmap<string, string>Empty for a VAPID assertion or generic OAuth 2.0 Connection. Otherwise the GitHub permission ceiling, for example {"contents": "write", "pull_requests": "write"}. administration is read only; organization permissions are refused. A policy with actors carries at most contents and pull_requests.
repositoriesstring[]Empty for a VAPID assertion or generic OAuth 2.0 Connection. Otherwise 1 to 1000 exact owner/name entries, no wildcard, each owned by the Connection's account. One exchange covers exactly one repository.
credential_kindCredentialKindWhat Broker issues: access_token or vapid_assertion on the wire. Required. One of access_token, runner_registration, vapid_assertion.
max_ttldurationThe longest a credential lives: GitHub default/maximum 3600s; OAuth 2.0 and VAPID default/maximum 86400s (capped by upstream expiry). Positive whole seconds only for VAPID.
actorsstring[]The Agents a delegated grant may act for: an Agent name orgs/{org}/projects/{project}/envs/{env}/agents/{agent}, or every Agent of an environment, .../envs/{env}/agents/*. 0 to 64. When set, only a delegated grant whose actor matches may exchange; a grant with no actor is refused. When empty, any grant of a subject may exchange, delegated or not.
github_action_budgetGitHubActionBudgetRequired for GitHub user actions. Zero denies actions; ceilings are 80 per minute and 500 per hour. This policy budget does not replace GitHub limits.

TrustPolicyStatus

FieldTypeWhat it is
observed_generationint64The generation this status was computed from. Output only.
conditionsCondition[]Ready: the policy was admitted against an active installation. A permission the installation lacks is refused at exchange with reason CapabilityMissing. Output only.

GitHubActionBudget

FieldTypeWhat it is
per_minuteint32Maximum admissions in a rolling 60-second window; 1 to 80. Required.
per_hourint32Maximum admissions in a rolling 3600-second window; 1 to 500. Required.

Condition

FieldTypeWhat it is
typestringThe condition type, for example Ready.
statusConditionStatusWhether the condition holds. One of true, false, unknown.
observed_generationint64The generation this observation was made against.
reasonstringA machine-readable UpperCamelCase reason.
messagestringA customer-safe human-readable message.
severitySeverityHow severe a FALSE condition is. One of info, warning, error.
transition_timetimestampWhen status last changed.

Errors

Every error arrives in the body Errors describes.

Examples

curl -X PATCH "https://api.sylphx.com/v1/orgs/acme/trust_policies/trust-policy" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"orgs/acme/trust_policies/trust-policy","spec":{"connection":"…","credential_kind":"access_token","subjects":["…"]}}'