# Get the message permission for a sender/box combination

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

**GET** `/permissions/get`

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

Retrieves the permission record for a specific sender + message box pair
owned by the authenticated user. If `sender` is omitted, returns the
box-wide default. Returns `permission: null` when no record is set.

## Authorization

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

## Query parameters

- `sender` (string)
  Identity key of the sender to look up. Omit for box-wide default.
- `messageBox` (string, required)
  Message box type to check.

## Responses

### 200

Permission found or confirmed absent.

- `status` ("success", required)
- `description` (string, required)
- `permission` (object)
  The permission record, or null if not set.
  - `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>)

Example:

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

### 400

Missing or invalid parameters.
Codes: `ERR_MISSING_PARAMETERS`, `ERR_INVALID_PUBLIC_KEY`

- `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_AUTHENTICATION_REQUIRED`).

- `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_INTERNAL`).

- `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"
}
```