Grant API
Propose exact directional selections, collect endpoint approvals, and activate or revoke grant revisions.
Propose exact directional selections, collect endpoint approvals, and activate or revoke grant revisions.
Use the shared request contract for authentication, pagination, preconditions, idempotency, and common errors. Exact response members are defined in API data types and the downloadable OpenAPI contract.
List grants
/api/v1/connector/organizations/{organization_id}/connections/{connection_id}/grantsLists directional selections and their approval and activation states.
limitintegeroptionalNumber of records; bounds are inclusive.
50rule1–200cursorstringoptionalOpaque continuation; preserve the original filters.
Returns a data array of Grant records, pagination.next_cursor, and request_id.
Propose a grant
/api/v1/connector/organizations/{organization_id}/connections/{connection_id}/grantsCreates an immutable selection for endpoint review.
Requires If-Match from a current read. Requires Idempotency-Key.
Use the connection ETag. The source and destination must differ. Unavailable scopes, invalid category directions, and label keys outside the source permission return 422 invalid_selection. A replacement leaves the active grant unchanged until activation.
sourcestringrequiredSource endpoint side.
destinationstringrequiredOther endpoint side; must differ from source.
source_scope_idsstring[]requiredExplicit source projects, groups, or custom integration ID; no wildcard.
destination_scope_idstringrequiredReceiving project, asset group, or integration ID.
categoriesstring[]requiredNonempty categories supported by this direction.
label_keysstring[]optionalInventory labels permitted to cross the boundary; omitted shares no labels.
[]ruleAt most 20 itemsReturns data as Grant, plus request_id.
Read a grant
/api/v1/connector/organizations/{organization_id}/connections/{connection_id}/grants/{grant_id}Returns the exact selection, approvals, revision, and state.
Returns data as Grant, plus request_id.
Approve or reject a grant
/api/v1/connector/organizations/{organization_id}/connections/{connection_id}/grants/{grant_id}/decisionsRecords one endpoint decision for the reviewed grant revision.
Requires If-Match from a current read. Requires Idempotency-Key.
Requires native product administrator authority for a native side, or Connector Administrator authority over a custom side.
An Integration Developer key cannot approve native product access. Rejected grants cannot activate; propose a corrected selection.
sidestringrequiredSide for which the caller has approval authority.
decisionstringrequiredApprove or reject the reviewed revision.
reasonstringrequiredAudited explanation.
Returns data as Grant, plus request_id.
Activate a replacement grant
/api/v1/connector/organizations/{organization_id}/connections/{connection_id}/grants/{grant_id}/activateReplaces the active directional selection with an approved revision.
Requires If-Match from a current read. Requires Idempotency-Key.
Use the grant ETag. Both required approvals must match the revision or the request returns 409 approval_required.
Initial draft connections use connection activation. Read the connection after operation success to confirm the active grant generation.
reasonstringrequiredAudited reason; empty values are rejected.
Returns operation.id for operation polling and request_id; acceptance does not establish completion.
Revoke a grant
/api/v1/connector/organizations/{organization_id}/connections/{connection_id}/grants/{grant_id}/revokeStops subsequent exchange through the selected directional grant.
Requires If-Match from a current read. Requires Idempotency-Key.
Poll the operation and confirm revoked on the grant. Received copies retain destination access and retention rules; revocation does not recall them.
reasonstringrequiredAudited reason; empty values are rejected.
Returns operation.id for operation polling and request_id; acceptance does not establish completion.