> ## Documentation Index
> Fetch the complete documentation index at: https://wordsmithai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

Gives a [support member](https://wordsmithai.mintlify.site/api-reference/support-access/list-support-members.md) 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](https://wordsmithai.mintlify.site/api-reference/support-access/get-support-access-policy.md):

* **`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

**member\_id** `string` *required*

The support member who gets access. Its sign-in mode must still be allowed by your policy.

**role\_id** `string` *required*

An active custom role from [List roles](https://wordsmithai.mintlify.site/api-reference/organisation/list-roles.md) that your support settings allow (`support_role_ids`).

**scope** `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.

**resources** `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.

**starts\_at** `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.

**ends\_at** `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.

**ticket\_ref** `string`

The support ticket this access is for, up to 200 characters. Required when `require_ticket` is on.

**ticket\_url** `string`

A link to the ticket: an http or https URL of up to 2,000 characters.

**justification** `string`

Why the engineer needs access, up to 4,000 characters. Required when `require_justification` is on.

**data\_owner\_id** `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.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://api.wordsmith.ai/api/v1/support-access/grants" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "member_id": "5b0e6f1e-8a43-4f0e-9d0a-3e2c51f8a7b4",
  "ticket_ref": "SUP-1042",
  "ticket_url": "https://support.example.com/tickets/1042",
  "justification": "Reproduce the export failure on the Q3 supplier contracts repository.",
  "data_owner_id": "828b17cf-5f09-4edd-bcba-9d1de130a2e6",
  "resources": [
    {
      "kind": "repository",
      "id": "0f6a3c1e-2b4d-4e8f-9a1b-3c5d7e9f1a2b"
    }
  ],
  "role_id": "72f02d30-2d67-40b0-b5cb-859dbb45d485",
  "ends_at": "2026-11-17T14:00:00Z"
}'
```

```json Response theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "9d4c2b7a-1f3e-4a5b-8c6d-7e8f9a0b1c2d",
  "member_id": "5b0e6f1e-8a43-4f0e-9d0a-3e2c51f8a7b4",
  "requested_by": "4c98ef69-d5ef-4471-a2b8-89ded5b7b121",
  "requested_by_wordsmith": false,
  "ticket_ref": "SUP-1042",
  "ticket_url": "https://support.example.com/tickets/1042",
  "justification": "Reproduce the export failure on the Q3 supplier contracts repository.",
  "data_owner_id": "828b17cf-5f09-4edd-bcba-9d1de130a2e6",
  "scope": "resources",
  "resources": [
    {
      "kind": "repository",
      "id": "0f6a3c1e-2b4d-4e8f-9a1b-3c5d7e9f1a2b",
      "name": "Supplier contracts Q3"
    }
  ],
  "role_id": "72f02d30-2d67-40b0-b5cb-859dbb45d485",
  "starts_at": "2026-11-17T10:00:00Z",
  "ends_at": "2026-11-17T14:00:00Z",
  "separate_approvers": false,
  "required_approvals": [
    "admin"
  ],
  "requested_at": "2026-11-17T09:55:00Z",
  "approval_expires_at": "2026-11-18T09:55:00Z",
  "status": "approved",
  "phase": "active",
  "approvals": [
    {
      "role": "admin",
      "user_id": "4c98ef69-d5ef-4471-a2b8-89ded5b7b121",
      "approved": true,
      "decided_at": "2026-11-17T09:55:00Z",
      "comment": null
    }
  ],
  "closed_by": null,
  "closed_by_wordsmith": false,
  "closed_at": null,
  "close_reason": null
}
```

## Errors

| Status | `error_code` | When |
| - | - | - |
| 400 | `invalid_request_body` | A field is missing, has the wrong type, or an id is not an id from this API. |
| 400 | `bad_request` | The member is not an active support member or its sign-in mode is no longer allowed, the data owner is not an active member, the role is not active or not in your support settings' allowed roles, a resource does not exist in your organisation, you cannot see it, or it is listed twice, `scope` and `resources` disagree, `ticket_url` is not an http or https link, or the window is not valid. Your support settings can also refuse it: a missing ticket, justification, data owner or end, an end past `max_grant_minutes`, or `organisation` scope. The message says which. |
| 403 | `insufficient_scope` | The OAuth token does not hold `directory:admin`. |
| 403 | `forbidden` | The caller lacks the manage support access permission, is a Wordsmith support member, or support access is off for your organisation. Also returned for `organisation` scope or a role with an administrative permission when the caller cannot assign roles. |
| 403 | `aob_credential_blocked` | Wordsmith staff are acting on behalf of the caller. |
| 409 | `resource_conflict` | The support member already has an open request or grant. Close it first. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.