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

# Workspace settings

> The settings of each environment: the thresholds, the block threshold, the default depth and the admission of each flow, and the retention period. Read them with GET and change them with PATCH on /v1/workspaces/{workspace_id}/settings/{environment}.

Each environment of your workspace, `live` and `test`, has its own settings. They set how NoResponse decides each flow and how long it keeps assessments. The settings API reads and changes them.

| Route | What it does | Who can call it |
| - | - | - |
| `GET /v1/workspaces/{workspace_id}/settings/{environment}` | Answers the settings in force. | Every member of the workspace. |
| `PATCH /v1/workspaces/{workspace_id}/settings/{environment}` | Changes only the fields that the body names, in one transaction. | An admin or an owner of the workspace. |

`environment` is `live` or `test`. The settings routes take a console credential that acts for one member of the workspace. They refuse an API key with 403 [`workspace_forbidden`](https://docs.noresponse.org/problems/workspace-forbidden). For this reason they are not in the interactive reference.

A change reaches new assessments within one minute. An assessment keeps the settings that it was scored with. Every change goes into the audit log of the workspace as `settings.updated`, with the member who made it.

## The settings of a flow

`flows` holds one object for each flow: `account_creation`, `login` and `purchase`.

**step\_up** `integer`

The score from which the decision is `step_up`. The default is 40.

**review** `integer`

The score from which the decision is `review`. The default is 75.

**block** `integer`

The score from which the decision is `block`, from `review` to 100. It is absent while blocking is off, which is the default. Send `null` to turn blocking off.

**default\_depth** `string`

The `depth` of a request for this flow that names no depth. The default is `full` for `account_creation` and `purchase`, and `quick` for `login`.

**inherits\_account\_creation** `boolean`

`true` while `login` or `purchase` uses the thresholds of `account_creation`, which is the default. When you set a threshold on the flow, it gets its own thresholds, which start from those of `account_creation`. Send `true` to use the thresholds of `account_creation` again.

**admission** `string`

`immediate`, the default, or `held`. [Admission and late decisions](https://docs.noresponse.org/guides/late-results.md) explains the two.

**hold\_seconds** `integer`

How long a held flow waits for the investigation, from 30 to 86,400 seconds. The default is 300.

**on\_expiry** `string`

The decision of a held flow when `hold_seconds` pass first: `allow`, `review` or `block`. The default is `review`. When the evidence so far gives a stricter decision, that decision applies.

After a change, each flow must keep `step_up` below `review`, and `block` off or at least `review`. A change that breaks this rule answers 400 and names the flow.

## Other settings

**retention\_days** `integer`

How many days NoResponse keeps an assessment, from 1 to 365. The default is 365. See [Data retention](https://docs.noresponse.org/reference/data-retention.md).

**policy\_version** `integer`

How many times the `flows` settings of this environment changed. It is 0 while the defaults apply. A served `detail.risk.policy_version` ends in `+t` and this number once it is above 0.

**updated\_by** `string`

The member who made the last change. It is absent while the defaults apply.

## Turn blocking on

Without a block threshold, no decision is `block`. A hosted [deny at account creation](https://docs.noresponse.org/guides/deny-at-account-creation.md) integration then denies nothing. This body blocks account creations from a score of 90 in the environment that the URL names:

```json title="PATCH /v1/workspaces/{workspace_id}/settings/live" theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{ "flows": { "account_creation": { "block": 90 } } }
```

`login` and `purchase` use the thresholds of `account_creation` until you give them their own, so they also block from 90. A threshold of 75, the default review threshold, blocks everything that would go to review. To turn blocking off again, send `"block": null`.

When a block threshold is set, every assessment carries it:

| Field | Value |
| - | - |
| `account.risk.decision` | `block` when the account's score is at or above the threshold. |
| `detail.risk.block` | `true` when this assessment's `detail.risk.score` is at or above the threshold, otherwise `false`. |
| `detail.risk.block_threshold` | The threshold that the answer used. It is absent while blocking is off. |
| `detail.risk.policy_version` | Ends in `+t` and the `policy_version` of the settings. |

A test environment blocks from 90 until you set its own threshold. The [simulator](https://docs.noresponse.org/testing.md#magic-identifiers) uses that threshold.

## Hold a flow

This body holds account creation for up to 10 minutes, and sends an account to review when the investigation does not complete in time:

```json title="PATCH /v1/workspaces/{workspace_id}/settings/live" theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{ "flows": { "account_creation": { "admission": "held", "hold_seconds": 600, "on_expiry": "review" } } }
```

## The answer

`GET` and `PATCH` both answer the settings in force. These are the defaults of a test environment:

```json title="200 settings" theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "workspace_id": "tnt_01JA2Z8K6Q4V7W9XBCDEFGHJKM",
  "environment": "test",
  "retention_days": 365,
  "policy_version": 0,
  "flows": {
    "account_creation": { "step_up": 40, "review": 75, "default_depth": "full", "inherits_account_creation": false, "admission": "immediate", "hold_seconds": 300, "on_expiry": "review" },
    "login": { "step_up": 40, "review": 75, "default_depth": "quick", "inherits_account_creation": true, "admission": "immediate", "hold_seconds": 300, "on_expiry": "review" },
    "purchase": { "step_up": 40, "review": 75, "default_depth": "full", "inherits_account_creation": true, "admission": "immediate", "hold_seconds": 300, "on_expiry": "review" }
  }
}
```


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