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

# Overview

> Identity Controls API reference

The Identity Controls API provides management of various lifecycle actions on the Identity. This API replaces the
deprecated `user_disabled` and `admin_disabled` fields on the Identity API and expands allowing finer grained reasons and new types (`DORMANT`) of controls.

## Available Endpoints

### List Identity Controls

**GET /v2/identity/controls**
List all controls for an identity. Returns both active and deleted controls based on query parameters.

### Create Identity Control

**POST /v2/identity/controls**
Create a new control for an identity. Clients can only create `SELL_ONLY`, `CLOSED`, or `DORMANT` controls.

### Delete Identity Control

**DELETE /v2/identity/controls**
Delete a control to reactivate an identity. Only `is_overridable: true` controls can be deleted.

## Authentication

All endpoints require OAuth2 authentication with the following scopes:

* **`identity:read_identity_control`**: Required for listing controls
* **`identity:write_identity_control`**: Required for creating and deleting controls

## Control Types

| Type        | Description                                        |
| ----------- | -------------------------------------------------- |
| `SELL_ONLY` | Identity may only sell                             |
| `CLOSED`    | Identity is closed and may not perform any actions |
| `FROZEN`    | Identity is frozen due to compliance reasons       |
| `DORMANT`   | Identity is dormant due to inactivity              |

Being `SELL_ONLY`, `CLOSED`, `FROZEN`, or `DORMANT` will affect the Identity's ability to perform actions on the Platform.

## Control Overridability

Controls created via `CreateIdentityControl` create will be `is_overridable: true` and you'll be able to delete these controls.
In some scenarios Paxos will enforce an account closure or other type of control with `is_overridable: false` and you'll not be able to delete these controls.

## Response Format

Controls are returned in the following structure:

```json theme={null}
{
  "id": "59b8e3c5-2b6e-4fa6-afcf-8c685598241d",
  "type": "SELL_ONLY",
  "set_by": "CLIENT",
  "is_overridable": true,
  "reason_code": "END_USER_REQUESTED",
  "reason": "User requested",
  "created_at": "2024-01-15T10:30:00Z",
  "deleted_at": null
}
```

Active identity controls are also visible in the `status_details.active_controls` field when retrieving an identity via [GetIdentity](/api-reference/endpoints/identity/get-identity) or [ListIdentities](/api-reference/endpoints/identity/list-identities).

## Migration from Legacy Fields

Identity Controls replaces the deprecated `user_disabled` and `admin_disabled` boolean fields. Existing identities with these fields set will be automatically migrated to use Identity Controls. During the transition period, both the legacy fields and Identity Controls will be supported.

**Migration mapping:**

* `user_disabled: true` → Identity Control with `type: SELL_ONLY`, `set_by: CLIENT`, `is_overridable: true`
* `admin_disabled: true` → Identity Control with `type: SELL_ONLY`, `set_by: PAXOS`, `is_overridable: false`