Skip to main content
POST
Gives a support member a custom role on the items you name (scope: resources), or across your organisation (scope: organisation), from starts_at until ends_at, or until revoked when ends_at is left out. What happens depends on approvals in your support settings:
  • requester (the default): the access is given at once. The response has status: approved, with your approval recorded as the admin’s.
  • another_person: it is a request. It gives no access until an admin other than you approves it before approval_expires_at.
  • data_owner_and_another: it is a request. It gives no access until the data owner and an admin both approve it before approval_expires_at. They are two different people, and neither is you.
Approving and rejecting are not available through the API or the MCP server. Both need a recent sign-in, which an API key or token cannot prove, so approvers decide in the web app. Your support settings also decide what a grant must include. require_ticket, require_justification and require_data_owner make those fields required, and data_owner_and_another always needs a data owner. max_grant_minutes needs an end within that many minutes. allow_customer_scope off allows named items only. The role must be one of support_role_ids. With the defaults, the fields are optional and organisation scope is allowed; no role is allowed until you list one. The scope never changes after the grant is created. To extend or widen access, revoke it and give it again. A support member has at most one open grant at a time. A session in which Wordsmith staff act on behalf of one of your members cannot give access.

Authentication

Requires an API key, or an OAuth token with directory:admin. directory:admin is never granted by default. The caller must also hold a role with the manage support access permission; the predefined admin role holds both. A Wordsmith support member is always refused, whatever role it holds. Support access must be turned on for your organisation.

Body parameters

string
required
The support member who gets access. Its sign-in mode must still be allowed by your policy.
string
required
An active custom role from List roles that your support settings allow (support_role_ids).
enum
default:"resources"
resources gives the role on the items in resources only. organisation gives it across your organisation and takes no resources; it needs allow_customer_scope on. Organisation-wide access, or a role with an administrative permission, also needs permission to assign roles.
object[]
What the engineer may see, up to 50 distinct items, for resources scope. Each has kind (repository, session, report or review) and id. You can name only items you can see yourself.
string
When access starts, as an ISO 8601 time with a time zone. Defaults to now. A start up to five minutes in the past is treated as now, to absorb clock skew; an earlier one is refused.
string
When access ends. Leave it out for access until revoked. When max_grant_minutes is set, the end must fall within that many minutes of starts_at, and time spent waiting for approval comes out of that window.
string
The support ticket this access is for, up to 200 characters. Required when require_ticket is on.
string
A link to the ticket: an http or https URL of up to 2,000 characters.
string
Why the engineer needs access, up to 4,000 characters. Required when require_justification is on.
string
The member who owns the data. They must be able to manage who sees every item in the grant, and under data_owner_and_another they approve. Required when require_data_owner is on or approvals is data_owner_and_another.

Response

Returns 201 with the new grant: approved and active under requester, or requested and awaiting_approval when it needs approval.

Errors