BSV blockchainBSV blockchain

List message permissions for the authenticated user

GET/permissions/list

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.

Query Parameters

messageBoxstring

Filter results to a specific message box type.

limitinteger

Maximum number of records to return.

offsetinteger

Number of records to skip (for pagination).

createdAtOrderstring

Sort order for created_at (newest first by default).

Response

Permission list retrieved.

status"success"
permissionsobject[]
Show permissions properties
senderstring

Sender identity key, or null for a box-wide default.

messageBoxstring
recipientFeeinteger

-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)
createdAtstring<date-time>
updatedAtstring<date-time>
totalCountinteger

Total count before pagination (useful for building page controls).

Invalid pagination parameters. Codes: ERR_INVALID_LIMIT, ERR_INVALID_OFFSET

status"error"
codestring

Machine-readable error code (see specs/errors.md).

descriptionstring

Human-readable explanation.

Authentication required (ERR_UNAUTHORIZED).

status"error"
codestring

Machine-readable error code (see specs/errors.md).

descriptionstring

Human-readable explanation.

Internal server error (ERR_LIST_PERMISSIONS_FAILED).

status"error"
codestring

Machine-readable error code (see specs/errors.md).

descriptionstring

Human-readable explanation.

Request
curl -X GET "https://{host}/permissions/list?messageBox=<messageBox>&limit=<limit>&offset=<offset>&createdAtOrder=<createdAtOrder>" \
  -H "x-bsv-auth-identity-key: <x-bsv-auth-identity-key>"
Response
{
  "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
}