# List message permissions for the authenticated user

> For the complete documentation index, see [llms.txt](https://bsvblockchain.com/docs/llms.txt).

**GET** `/permissions/list`

Base URL: `https://{host}`

Returns one bounded page of permission records owned by the
authenticated identity, with optional filtering. Results are ordered by
`(message_box ASC, normalized sender scope ASC, created_at DESC/ASC)`.
Box-wide defaults (sender = null) use the empty normalized scope and
therefore appear before sender-specific entries within each message box.

## Authorization

- x-bsv-auth-identity-key (apiKey in header)

## Query parameters

- `messageBox` (string)
  Filter results to a specific message box type.
- `limit` (integer)
  Maximum number of records to return.
- `offset` (integer)
  Number of records to skip (for pagination).
- `createdAtOrder` (string)
  Sort order for `created_at` (newest first by default).

## Responses

### 200

Permission list retrieved.

- `status` ("success", required)
- `permissions` (object[], required)
  - `sender` (string)
    Sender identity key, or null for a box-wide default.
  - `messageBox` (string)
  - `recipientFee` (integer)
    -1 = blocked, 0 = always allow, positive = satoshi amount required.
  - `status` ("always_allow" | "blocked" | "payment_required")
    - `always_allow` — recipientFee is 0
    - `blocked`      — recipientFee is -1
    - `payment_required` — recipientFee is a positive integer (satoshi amount)
  - `createdAt` (string<date-time>)
  - `updatedAt` (string<date-time>)
- `totalCount` (integer, required)
  Total count before pagination (useful for building page controls).

Example:

```json
{
  "status": "success",
  "permissions": [
    {
      "sender": "string",
      "messageBox": "string",
      "recipientFee": 0,
      "status": "always_allow",
      "createdAt": "1970-01-01T00:00:00.000Z",
      "updatedAt": "1970-01-01T00:00:00.000Z"
    }
  ],
  "totalCount": 0
}
```

### 400

Invalid pagination parameters.
Codes: `ERR_INVALID_LIMIT`, `ERR_INVALID_OFFSET`

- `status` ("error", required)
- `code` (string, required)
  Machine-readable error code (see specs/errors.md).
- `description` (string, required)
  Human-readable explanation.

Example:

```json
{
  "status": "error",
  "code": "string",
  "description": "string"
}
```

### 401

Authentication required (`ERR_UNAUTHORIZED`).

- `status` ("error", required)
- `code` (string, required)
  Machine-readable error code (see specs/errors.md).
- `description` (string, required)
  Human-readable explanation.

Example:

```json
{
  "status": "error",
  "code": "string",
  "description": "string"
}
```

### 500

Internal server error (`ERR_LIST_PERMISSIONS_FAILED`).

- `status` ("error", required)
- `code` (string, required)
  Machine-readable error code (see specs/errors.md).
- `description` (string, required)
  Human-readable explanation.

Example:

```json
{
  "status": "error",
  "code": "string",
  "description": "string"
}
```