BSV blockchainBSV blockchain

Get the message permission for a sender/box combination

GET/permissions/get

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.

Query Parameters

senderstring

Identity key of the sender to look up. Omit for box-wide default.

messageBoxstringrequired

Message box type to check.

Response

Permission found or confirmed absent.

status"success"
descriptionstring
permissionobject

The permission record, or null if not set.

Show permission 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>

Missing or invalid parameters. Codes: ERR_MISSING_PARAMETERS, ERR_INVALID_PUBLIC_KEY

status"error"
codestring

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

descriptionstring

Human-readable explanation.

Authentication required (ERR_AUTHENTICATION_REQUIRED).

status"error"
codestring

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

descriptionstring

Human-readable explanation.

Internal server error (ERR_INTERNAL).

status"error"
codestring

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

descriptionstring

Human-readable explanation.

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