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

# Update App Settings

> configure an app's authentication settings

Update authentication settings for an app.

## Endpoint

```
PATCH /v1/apps/:app_id
```

## Authentication

Send your workspace (or app-scoped) API secret as a Bearer token.

```http theme={null}
Authorization: Bearer <api_secret_key>
Content-Type: application/json
```

The bearer must own the app:

* **Workspace key** (`scwor_…`) — can manage any app in the workspace
* **App key** (`scapp_…`) — can only manage its own app

Wrong scope returns `403 "API key not authorized for this app"`.

## Body

Wrap fields in an `app` object. All fields are optional. send only what you want to change.

### Token lifetimes

All values are in **seconds**.

| Field                   | Default  | Typical range   | Description                       |
| ----------------------- | -------- | --------------- | --------------------------------- |
| `access_expiration`     | `3600`   | 60 – 604800     | Access token TTL                  |
| `refresh_expiration`    | `604800` | 3600 – 31536000 | Refresh token TTL                 |
| `magic_link_expiration` | `2000`   | 60 – 604800     | Magic link TTL                    |
| `otp_expiration`        | `600`    | 30 – 3600       | OTP code TTL                      |
| `session_timeout`       | `604800` | —               | Session inactivity timeout        |
| `auto_refresh`          | `true`   | bool            | Auto-refresh access tokens        |
| `refresh_payload`       | `true`   | bool            | Include payload in refresh tokens |

### Other common fields

`name`, `origin`, `additional_origins[]`, `mfa_policy`, `mfa_methods_allowed[]`, `email_required`, `phone_number_required`, `passkeys_enabled`, `email_auth_type` (`magic` or `otp`), `otp_length`.

## Example

```bash theme={null}
curl -X PATCH https://api.scute.io/v1/apps/app_l3RxEBGbQq5Q0b6T6K6N \
  -H "Authorization: Bearer $SCUTE_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "app": {
      "access_expiration": 7200,
      "refresh_expiration": 1209600
    }
  }'
```

## Response — `200 OK`

```json theme={null}
{
  "app": {
    "id": "app_l3RxEBGbQq5Q0b6T6K6N",
    "name": "...",
    "access_expiration": 7200,
    "refresh_expiration": 1209600,
    "magic_link_expiration": 2000,
    "otp_expiration": 600,
    "session_timeout": 604800,
    "auto_refresh": true,
    "...": "..."
  }
}
```

Changes take effect on the **next token issued**, existing tokens keep their original expiration until they expire naturally.

## Errors

| Status | When                                                                  |
| ------ | --------------------------------------------------------------------- |
| `401`  | Missing or invalid API key                                            |
| `403`  | API key isn't authorized for this app (wrong workspace)               |
| `404`  | App not found                                                         |
| `422`  | Validation error (e.g. malformed `origin`) — error message in `error` |