Central Chat HTTPS API v1

The AeroNyx Central Chat API lets a server, bot, or application exchange client-sealed chat envelopes with AeroNyx identities over ordinary HTTPS. It does not use the AeroNyx Privacy Network, VPN, onion routing, or anonymous mailbox.

Base URL: https://api.aeronyx.network/api/relay/developer/v1

Security model

• An identity is an Ed25519 key pair. Generate it locally and keep the private key in your own keystore. AeroNyx never receives it.
• The 32-byte public key, encoded as 64 lowercase hexadecimal characters, is the chat address.
• Message content is an AeroNyx-compatible sealed envelope. The API stores and forwards only the Base64 ciphertext.
• The centralized relay can observe sender and receiver public keys, message time, size, delivery state, and IP-level request metadata. HTTPS does not hide this metadata from the relay.
• Delivery is at least once. Persist and decrypt a message before acknowledging it; deduplicate by msg_id.

Request authentication

Every endpoint except GET /capabilities/ requires:

Authorization: AeroNyx-Chat-V1 <public-key-hex>:<unix-seconds>:<nonce-hex>:<signature-hex>

nonce-hex is 16 random bytes encoded as 32 lowercase hex characters and may be used only once. The timestamp must be within 60 seconds of server time.

Sign this 32-byte digest with Ed25519:

SHA256(
  "AeroNyx/DeveloperChatRequestV1\0" ||
  UPPERCASE_HTTP_METHOD || "\0" ||
  PATH_WITH_QUERY || "\0" ||
  ASCII_UNIX_SECONDS || "\0" ||
  NONCE_BYTES ||
  SHA256(EXACT_HTTP_BODY_BYTES)
)

The query string is part of PATH_WITH_QUERY. JSON whitespace and key order therefore matter: sign the exact bytes you send.

Create an identity

from nacl.signing import SigningKey

private_key = SigningKey.generate()
public_key_hex = private_key.verify_key.encode().hex()
# Store private_key.encode() in a secret manager. Publish only public_key_hex.

Creating a key does not create an AeroNyx account. It creates a compatible cryptographic chat identity.

Send a sealed message

POST /messages/

{
  "receiver_pubkey": "<64 lowercase hex characters>",
  "message_id": "018f5164-c1b2-7e2b-9d8a-2c60597f4c2f",
  "discriminant": 11,
  "sent_at": 1780000000,
  "payload_b64": "<AeroNyx-compatible sealed envelope>"
}

Use a random UUID once and retain the exact body for retries. Reusing the same message_id with different fields returns idempotency_conflict. A successful request returns HTTP 202:

{
  "message_id": "018f5164-c1b2-7e2b-9d8a-2c60597f4c2f",
  "accepted": true,
  "delivered_live": false
}

accepted means the relay durably admitted the ciphertext. It does not mean the recipient decrypted or displayed it.

Pull the inbox

GET /inbox/?limit=50

The response contains up to 100 unacknowledged opaque events. The same event can appear again after a timeout or restart.

{
  "messages": [{
    "sender_pubkey": "<hex>",
    "discriminant": 11,
    "payload_b64": "<ciphertext>",
    "timestamp": 1780000000,
    "msg_id": "018f5164-c1b2-7e2b-9d8a-2c60597f4c2f"
  }],
  "has_more": false
}

Acknowledge persisted messages

POST /acks/

{
  "message_ids": ["018f5164-c1b2-7e2b-9d8a-2c60597f4c2f"]
}

Only acknowledge after the ciphertext has been validated, decrypted, and durably written locally. Unknown IDs are omitted from acknowledged.

Limits and errors

• Maximum sealed payload: 191 KiB (the Base64 JSON request remains below the 256 KiB request ceiling).
• Maximum request body: 256 KiB.
• Maximum inbox page and ACK batch: 100 items.
• Offline ciphertext retention: currently 72 hours; clients must not treat the relay as permanent history.
• 401: missing, expired, invalid, or replayed request authentication.
• 403: recipient policy rejected this sender.
• 409: idempotency conflict or an identical request is still in progress.
• 429: sender rate limit reached; honor Retry-After.
• 503: durable delivery or authentication infrastructure unavailable; retry the exact message body with a fresh authentication nonce.

Compatibility boundary

This API is the transport boundary. The official AeroNyx envelope codec and key agreement remain the compatibility boundary for messages intended for the AeroNyx App. Do not send plaintext in payload_b64. A small client SDK and golden envelope vectors will be published separately; until then, integrations should use the existing AeroNyx client codec to produce and open envelopes.