Build on the Coveton API.

The Coveton API is a REST interface for everything around your encrypted communication: user identity, organizations, teams and roles, device registration, session management, encrypted message transport, file storage and billing. It is the same API that powers the Coveton mobile app and admin dashboard.

Every request and response is JSON over HTTPS. Resources are organized around predictable, plural nouns, standard HTTP verbs describe intent, and HTTP status codes describe outcome. There are no SOAP envelopes, no GraphQL schema to learn, and no client library required to get started: any HTTP client works today.

Official and community SDKs are planned for cURL workflows plus JavaScript, TypeScript, Python, PHP, Ruby, Go, Java, C#, Rust, Swift and Kotlin. Until they ship, the examples throughout this reference show idiomatic, copy-pasteable requests in all twelve. Use the language switcher on any code block; your choice applies to every sample on the page.

Create an account, exchange your credentials for tokens, then call an authenticated endpoint. The login response returns a short-lived accessToken and a rotating refreshToken.

curl -X POST https://api.coveton.com/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "password": "a-strong-passphrase",
    "displayName": "Ada Lovelace"
  }'

With an accessToken in hand, every other call carries it in the Authorization header. Fetch the current user to confirm you are authenticated:

curl https://api.coveton.com/v1/auth/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Coveton uses bearer tokens. Send your access token on every authenticated request:

Access tokens are short-lived JWTs that expire after 15 minutes. Refresh tokens are long-lived but rotate on every use: each call to POST /v1/auth/refresh returns a fresh pair and invalidates the refresh token you just presented. Store the new pair and discard the old. If a refresh token is ever replayed, the whole token family is revoked.

curl -X POST https://api.coveton.com/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{ "refreshToken": "'"$REFRESH_TOKEN"'" }'

Calling POST /v1/auth/logout revokes the presented refresh token. To sign up or sign in with an identity provider, redirect the user to GET /v1/auth/oauth/google or GET /v1/auth/oauth/github; the callback completes the same token exchange.

Coveton is end-to-end encrypted, and that property is enforced at the protocol level, not by policy. Encryption and decryption happen on the client. The server stores and serves opaque ciphertext together with per-device key envelopes, and never holds the keys to read either. There is no server-side capability, technical or legal, to produce your plaintext.

The cryptographic key management, the Signal-style ratchet, and envelope sealing are implemented by the Coveton client SDK. Integrators building E2E flows should use it to produce ciphertext and envelopes rather than rolling their own crypto. The REST API documented here handles everything around that: transport, identity, organizations, devices, presence, files and billing.

All requests go to a single host, and every endpoint lives under the /v1 prefix. Requests and responses are JSON, sent and received over HTTPS only. Plain HTTP is rejected.

The major version is pinned in the path. Backwards-incompatible changes ship under a new prefix (for example a future /v2); additive changes such as new fields or new endpoints are made in place. Treat unknown JSON fields as forwards compatible and ignore the ones you do not use.

Coveton uses conventional HTTP status codes and returns a consistent error envelope on failure. The code is a stable machine-readable string, message is human-readable, and details is present on validation failures.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": {
    "code": "VALIDATION",
    "message": "Request validation failed.",
    "details": [
      { "path": "email", "message": "must be a valid email" }
    ]
  }
}

Error codes

The first column reuses the method chip purely as a colored marker; these rows describe codes, not endpoints.

The API allows 120 requests per minute, enforced both per IP address and per access token. Exceeding the limit returns 429 with the RATE_LIMITED code. Every response carries the current budget in its headers so you can throttle proactively rather than reactively.

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1718900000
Retry-After: 12

On a 429, honor Retry-After (seconds) before retrying. For bursty workloads, prefer exponential backoff with jitter and keep a single token per process to stay within the per-token budget.

List endpoints return JSON arrays. High-volume, time-ordered collections such as messages use cursor-based pagination with limit and a before cursor. Pass the id of the oldest item you have seen as before to walk backwards through history; stop when fewer than limit items come back.

curl "https://api.coveton.com/v1/chats/$CHAT_ID/messages?limit=50&before=$OLDEST_MESSAGE_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Coveton both sends and receives signed webhooks. Outbound webhooks notify your systems of platform events; inbound payment webhooks from your processor are delivered to /v1/webhooks/stripe, /v1/webhooks/paystack and /v1/webhooks/flutterwave, where Coveton verifies the provider signature before acting.

Every outbound delivery is signed. Verify it before trusting the body: recompute an HMAC over the raw request bytes using your endpoint signing secret, then compare against the signature header in constant time. Reject anything that does not match, and reject deliveries whose timestamp is outside a few minutes of now to blunt replays.

# Coveton signs each delivery; verify in your handler, not via curl.
# Header: X-Coveton-Signature: t=1718900000,v1=hexhmac
# Signed payload string: "{t}.{rawBody}"  (HMAC-SHA256, hex)

Network calls fail in ambiguous ways: a request can succeed on the server while the response is lost in transit. To make writes safe to retry, send a unique Idempotency-Key header on POST requests that create resources (sending a message, creating an organization, starting a checkout). Coveton records the first result for a key and replays it on any retry that carries the same key, so a resource is never created twice.

curl -X POST https://api.coveton.com/v1/messages \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f1c2b7e-3a4d-4f8a-9c2e-1b0d5e6f7a8b" \
  -d @message.json

Account creation, sessions and OAuth. These endpoints are public except for those that read the current identity.

Log in

curl -X POST https://api.coveton.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "ada@example.com", "password": "a-strong-passphrase" }'

Manage your own profile and look up other users to start conversations.

Organizations are the top-level tenant. They own members, teams, billing and audit logs. Creating one makes you its owner.

Create an organization

curl -X POST https://api.coveton.com/v1/organizations \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Analytical Engine Co", "slug": "analytical-engine" }'

Within an organization, structure is expressed through teams, departments, roles, granular permissions and invites. Each resource supports standard CRUD. Roles bind a set of permissions; assigning a role to a member grants those permissions.

Every device that participates in encrypted messaging registers its public key so other members can seal envelopes to it. Removing a device revokes its ability to receive new messages.

Review active sessions across devices and revoke any of them remotely.

A chat is a conversation between devices, either one-to-one or a group. Messages belong to a chat and are listed newest-first with cursor pagination.

Messages carry ciphertext plus one envelope per recipient device. The client SDK produces both; the API only transports them. Each envelope holds a deviceId and an opaque header (the sealed message key for that device). An optional expiresAt turns the message into a self-destructing one.

Send an encrypted message

The body below is what the SDK hands you after encryption: opaque ciphertext and a sealed envelope per device. Coveton stores and routes it verbatim.

curl -X POST https://api.coveton.com/v1/messages \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "chatId": "chat_8f2a",
    "contentType": "text/plain",
    "ciphertext": "BASE64_OPAQUE_CIPHERTEXT",
    "envelopes": [
      { "deviceId": "dev_a1", "header": "SEALED_KEY_FOR_DEVICE_A1" },
      { "deviceId": "dev_b2", "header": "SEALED_KEY_FOR_DEVICE_B2" }
    ],
    "expiresAt": "2026-06-21T12:00:00Z"
  }'

Files are uploaded directly to storage, not through the API. Request a presigned URL, PUT the encrypted bytes to it, then reference the returned file id from a message. Downloads work the same way in reverse: ask for a short-lived download URL. Because the bytes you upload are already ciphertext, storage never sees plaintext.

Presign an upload

curl -X POST https://api.coveton.com/v1/files/presign \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "filename": "report.enc", "contentType": "application/octet-stream", "size": 482711 }'

# Response: { "fileId": "file_92ab", "uploadUrl": "https://...", "expiresIn": 900 }
# Then PUT the encrypted bytes straight to uploadUrl.

Each organization carries a subscription. Start a hosted checkout to begin or change a plan; the processor confirms the result through the payment webhooks described above. Paid invoices are available for reconciliation.

Create a checkout

curl -X POST https://api.coveton.com/v1/subscriptions/$ORG_ID/checkout \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "plan": "team_annual", "provider": "stripe", "successUrl": "https://app.example.com/billing" }'

# Response: { "checkoutUrl": "https://checkout.stripe.com/..." }

List in-app notifications and mark them as read.

Payment processors deliver events to these endpoints. Coveton verifies the provider signature before processing; unsigned or stale deliveries are rejected. See Webhooks for verification details.

Audit logs are append-only records of security-relevant actions across an organization: membership changes, role grants, device removals, session revocations and billing events. Filter by organization.