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

# Update support access policy

> Change how Wordsmith staff may reach your organisation's data.

Changes the settings you send and keeps the rest. An omitted or `null` field keeps its value, and at least one field must be set. The change is recorded in your audit log.

This endpoint only tightens the settings. If any field you send would loosen a setting, the whole change is refused with `403 forbidden`, and the message names the settings. Loosening needs the web app, under **Settings > Support access**. A field loosens a setting when it:

* adds a sign-in mode to `allowed_sign_in_modes`;
* turns `allow_customer_scope` or `get_support` on;
* adds a role to `support_role_ids`;
* moves `approvals` towards `requester` (the order is `requester`, `another_person`, `data_owner_and_another`);
* turns `require_ticket`, `require_justification` or `require_data_owner` off;
* raises `max_grant_minutes`, or `approval_window_minutes`.

Sending a setting's current value is allowed.

Tighter settings apply to open grants at once. Saving revokes every open grant that no longer fits: it covers your whole organisation and `allow_customer_scope` is off, it has no end or a longer window than `max_grant_minutes`, it lacks a ticket, justification or data owner that is now required, or it is still waiting for approval and `approvals` now asks for more. Removing a role from `support_role_ids` revokes every open grant that uses it. A grant already approved keeps the approvals it had. A support member whose sign-in mode is no longer allowed gets no new grant.

The Get support default role (`get_support_default_role_id`) is not changed here. Set it in the web app.

A session in which Wordsmith staff act on behalf of one of your members cannot change the settings.

## 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 settings permission; the predefined admin role holds both. The manage support access permission lets a member give access, but not change the settings. A Wordsmith support member is always refused, whatever role it holds. Support access must be turned on for your organisation.

## Body parameters

**allowed\_sign\_in\_modes** `string[]`

Which kinds of support member you allow: any of `customer_identity` and `wordsmith_driven`. Replaces the current list. It may only remove modes. An empty list allows none.

**approvals** `enum`

Who must approve a grant: `requester` (a member who manages support access gives access at once), `another_person` (an admin other than the requester), or `data_owner_and_another` (the data owner and an admin, two different people). It may only move towards `data_owner_and_another`.

**require\_ticket** `boolean`

Whether every grant needs a ticket.

**require\_justification** `boolean`

Whether every grant needs a justification.

**require\_data\_owner** `boolean`

Whether every grant needs a data owner.

**max\_grant\_minutes** `integer`

The longest window one grant may cover, from 15 to 10,080 minutes (seven days). It may only go down, or be set where there was no limit. Removing the limit needs the web app.

**allow\_customer\_scope** `boolean`

Whether a grant may cover your whole organisation rather than named items.

**support\_role\_ids** `string[]`

The custom roles a grant may use, by id from [List roles](https://wordsmithai.mintlify.site/api-reference/organisation/list-roles.md). Replaces the current list. It may only remove roles.

**get\_support** `boolean`

Whether members may ask for support from an item's share menu. Only `false` is allowed here.

**approval\_window\_minutes** `integer`

How long a request waits for its approvals before it lapses, from 15 to 10,080 minutes. It may only go down.

## Response

Returns `200` with the updated policy and what the change did to open access:

* `revoked_grant_count`: the open grants this change revoked.
* `still_open_grant_count`: the open grants the new settings no longer allow but Wordsmith could not revoke yet. Wordsmith retries each within minutes. Until then the grant still gives access; revoke it yourself if you need it closed at once.
* `withdrawn_request_count`: the open Get support requests the new settings no longer allow, which this change withdrew.
* `requests_still_open`: `true` when such a request could not be withdrawn. No engineer can claim it; withdraw it in the web app.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X PATCH "https://api.wordsmith.ai/api/v1/support-access/policy" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "approvals": "data_owner_and_another",
  "require_ticket": true,
  "max_grant_minutes": 480
}'
```

```json Response theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "allowed_sign_in_modes": [
    "customer_identity"
  ],
  "approvals": "data_owner_and_another",
  "require_ticket": true,
  "require_justification": true,
  "require_data_owner": false,
  "max_grant_minutes": 480,
  "allow_customer_scope": false,
  "support_role_ids": [
    "72f02d30-2d67-40b0-b5cb-859dbb45d485"
  ],
  "get_support": false,
  "get_support_default_role_id": "72f02d30-2d67-40b0-b5cb-859dbb45d485",
  "approval_window_minutes": 720,
  "min_duration_minutes": 15,
  "max_duration_minutes": 10080,
  "revoked_grant_count": 1,
  "still_open_grant_count": 0,
  "withdrawn_request_count": 0,
  "requests_still_open": false
}
```

## Errors

| Status | `error_code` | When |
| - | - | - |
| 400 | `invalid_request_body` | The body sets no field to a value, a field has the wrong type or is not one listed here, a sign-in mode is not `customer_identity` or `wordsmith_driven`, or `approvals` is not one of its three values. |
| 400 | `bad_request` | A duration is outside 15 to 10,080 minutes. |
| 403 | `insufficient_scope` | The OAuth token does not hold `directory:admin`. |
| 403 | `forbidden` | The caller lacks the manage support settings permission, is a Wordsmith support member, or support access is off for your organisation. |
| 403 | `forbidden` | The body loosens a setting. The message names which. |
| 403 | `aob_credential_blocked` | Wordsmith staff are acting on behalf of the caller. |
| 409 | `resource_conflict` | Your settings changed while saving. Read them again and retry. |


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