Recipients API

Base URL: https://api.torvussecurity.com/v1

Manage vault recipients who will receive access when the vault releases.

---

List Recipients

GET /vaults/{vault_id}/recipients

Get all recipients for a vault.

Example Request

curl -X GET https://api.torvussecurity.com/v1/vaults/vault_abc123/recipients \
  -H "Authorization: Bearer your_api_key"

Success Response (200 OK)

{
  "data": [
    {
      "id": "recipient_xyz789",
      "email": "john@example.com",
      "name": "John Doe",
      "status": "verified",
      "added_at": "2025-10-01T10:00:00Z",
      "verified_at": "2025-10-01T10:30:00Z",
      "access_granted": false,
      "vault_id": "vault_abc123"
    },
    {
      "id": "recipient_abc456",
      "email": "jane@example.com",
      "name": "Jane Smith",
      "status": "pending",
      "added_at": "2025-10-05T14:00:00Z",
      "verified_at": null,
      "access_granted": false,
      "vault_id": "vault_abc123"
    }
  ],
  "pagination": {
    "total": 2
  }
}

---

Add Recipient

POST /vaults/{vault_id}/recipients

Add a new recipient to a vault.

Request Body

{
  "email": "recipient@example.com",
  "name": "Recipient Name",
  "send_notification": true
}

Parameters:

Field	Type	Required	Description
email	string	Yes	Recipient email address
name	string	No	Recipient name
send_notification	boolean	No	Send verification email (default: true)

Example Request

curl -X POST https://api.torvussecurity.com/v1/vaults/vault_abc123/recipients \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newrecipient@example.com",
    "name": "New Recipient",
    "send_notification": true
  }'

Success Response (201 Created)

{
  "id": "recipient_new123",
  "email": "newrecipient@example.com",
  "name": "New Recipient",
  "status": "pending",
  "added_at": "2025-10-08T15:30:00Z",
  "verified_at": null,
  "access_granted": false,
  "vault_id": "vault_abc123",
  "verification_sent": true
}

Error Responses

Status Code	Error	Description
400	Bad Request	Invalid email address
401	Unauthorized	Missing or invalid API key
402	Payment Required	Recipient limit reached
403	Forbidden	No permission to add recipients
409	Conflict	Recipient already exists
422	Unprocessable Entity	Vault already released

---

Get Recipient

GET /recipients/{recipient_id}

Get recipient details.

Example Request

curl -X GET https://api.torvussecurity.com/v1/recipients/recipient_xyz789 \
  -H "Authorization: Bearer your_api_key"

Success Response (200 OK)

{
  "id": "recipient_xyz789",
  "email": "john@example.com",
  "name": "John Doe",
  "status": "verified",
  "added_at": "2025-10-01T10:00:00Z",
  "verified_at": "2025-10-01T10:30:00Z",
  "access_granted": false,
  "last_access": null,
  "vault_id": "vault_abc123",
  "metadata": {
    "ip_address": "192.168.1.1",
    "user_agent": "Mozilla/5.0..."
  }
}

---

Update Recipient

PATCH /recipients/{recipient_id}

Update recipient information.

Request Body

{
  "name": "Updated Name"
}

Success Response (200 OK)

{
  "id": "recipient_xyz789",
  "email": "john@example.com",
  "name": "Updated Name",
  "status": "verified",
  "updated_at": "2025-10-08T16:00:00Z"
}

---

Remove Recipient

DELETE /recipients/{recipient_id}

Remove a recipient from the vault.

Example Request

curl -X DELETE https://api.torvussecurity.com/v1/recipients/recipient_xyz789 \
  -H "Authorization: Bearer your_api_key"

Success Response (204 No Content)

No response body.

---

Resend Verification

POST /recipients/{recipient_id}/resend-verification

Resend verification email to unverified recipient.

Example Request

curl -X POST https://api.torvussecurity.com/v1/recipients/recipient_abc456/resend-verification \
  -H "Authorization: Bearer your_api_key"

Success Response (200 OK)

{
  "id": "recipient_abc456",
  "email": "jane@example.com",
  "verification_sent": true,
  "sent_at": "2025-10-08T16:15:00Z"
}

---

Rate Limits

Endpoint	Rate Limit
GET /vaults/{id}/recipients	100/minute
POST /vaults/{id}/recipients	20/minute
DELETE /recipients/{id}	20/minute

---

Last Updated: October 8, 2025