Device Management API

Device announcements create temporary routing mappings that allow servers to deliver messages to devices. Unlike traditional systems, Cryptid servers store no permanent device records; All mappings expire automatically after 24-48 hours.

Devices must periodically re-announce themselves to maintain message delivery. This approach ensures that server compromise reveals minimal metadata, as inactive devices are automatically forgotten.

Register Device

Creates a temporary delivery mapping and issues a JWT access token. The server performs only basic timestamp validation. Signature verification is the recipient’s responsibility, maintaining the minimal-trust model.

Caution

Device addresses are cryptographically derived from device IDs and cannot be changed. Each device has a unique, permanent address.

Endpoint

POST /v1/announce

Request

POST /v1/announce HTTP/1.1
Content-Type: application/json

{
    "device_address": "a1b2c3d4e5f61728394a5b6c7d8e9f10@chat.example.com",
    "announcement_signature": "ed25519_signature_over_address_and_timestamp",
    "timestamp": 1759695461,
    "storage_preferences": {
      "max_retention_days": 30,
      "offline_message_limit": 1000
    }
}

Parameters:

• device_address: Cryptographically derived device address (16 bytes hex + @ + domain)

• announcement_signature: Ed25519 signature over address and timestamp

• timestamp: Unix timestamp (prevents replay attacks)

• storage_preferences: Optional message storage settings

Response

{
  "assigned_address": "a1b2c3d4e5f61728394a5b6c7d8e9f10@chat.example.com",
  "access_token": "jwt_access_token",
  "expires_at": 1759695599,
  "server_capabilities": {
    "max_message_size": 10485760,
    "federation_enabled": true,
    "supported_mls_versions": ["1.0"],
    "rate_limits": {
      "messages_per_minute": 60,
      "announcements_per_hour": 24
    }
  },
  "next_announcement_required": 1759696000
}

Response Fields:

• assigned_address: The device’s routing address (same as request)

• access_token: JWT Bearer token for authenticated endpoints (expires with mapping)

• expires_at: Unix timestamp when the delivery mapping expires

• server_capabilities: Server limits and features for client configuration

• next_announcement_required: Recommended time for next keepalive announcement

Update Device Announcement

Extends the delivery mapping expiration. Devices should call this endpoint before their current mapping expires (typically every 20-24 hours) to ensure continuous message delivery. This is a lightweight keepalive that doesn’t require re-uploading storage preferences.

Endpoint

PUT /v1/announce

Request

PUT /v1/announce HTTP/1.1
Authorization: Bearer {access_token}
Content-Type: application/json

{
    "device_address": "a1b2c3d4e5f61728394a5b6c7d8e9f10@chat.example.com",
    "announcement_signature": "ed25519_signature_over_address_and_timestamp",
    "timestamp": 1759696179
}

Response (200K)

{
    "expires_at": 1759697179,
    "next_announcement_required": 1759699999
}

Deregister Device

Explicitly removes the device from the server’s routing table. While mappings expire automatically, explicit deregistration ensures immediate cleanup and prevents queuing messages for devices that are intentionally going offline.

Note

Any queued messages for this device remain available until their individual expiration times.

Endpoint

DELETE /v1/announce

Request

DELETE /v1/announce HTTP/1.1
Authorization: Bearer {access_token}
Content-Type: application/json

{
    "device_address": "a1b2c3d4e5f61728394a5b6c7d8e9f10@chat.example.com",
    "deregistration_signature": "ed25519_signature_over_address_and_timestamp",
    "timestamp": 1759699999
}

Response

{
    "status": "deregistered"
}

Important Notes

Signature Verification

The server validates that signatures are properly formatted but does not verify their cryptographic correctness. Recipients must verify signatures themselves using the sender’s public key. This prevents the server from making trust decisions.

Automatic Expiration

All device mappings expire after 24 hours by default. Queued messages expire according to max_retention_days (default: 30 days). No manual cleanup is required.

Rate Limiting

Device announcements are limited to 24 per hour per address. This allows for legitimate network reconnections while preventing announcement spam.

Example Flow

1. Device generates Ed25519 keypair locally.

2. Device derives device address from the device ID.

3. POST /v1/announce -> Receives JWT token.

4. Uses token for all subsequent API calls.

5. PUT /v1/announce every 20 hours (keepalive).

6. DELETE /v1/announce when going offline (optional).