Support access
Give or request support access
Give a Wordsmith engineer access to named items or your whole organisation, or request it where your support settings need approval.
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 hasstatus: 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 beforeapproval_expires_at.data_owner_and_another: it is a request. It gives no access until the data owner and an admin both approve it beforeapproval_expires_at. They are two different people, and neither is you.
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 withdirectory: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
The support member who gets access. Its sign-in mode must still be allowed by your policy.
An active custom role from List roles that your support settings allow (
support_role_ids).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.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.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.
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.The support ticket this access is for, up to 200 characters. Required when
require_ticket is on.Why the engineer needs access, up to 4,000 characters. Required when
require_justification is on.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
Returns201 with the new grant: approved and active under requester, or requested and awaiting_approval when it needs approval.