Admin REST API

Server-to-server (S2S) endpoints for managing your application’s users, passkeys, and data. All endpoints require an OAuth2 bearer token — not the publishable key.

Authentication

All admin endpoints require Authorization: Bearer <token> obtained from the OAuth2 client credentials flow.

curl -X POST https://api.trymellonauth.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_APP_ID",
    "client_secret": "YOUR_APP_SECRET",
    "grant_type": "client_credentials"
  }'

Response:

{ "access_token": "eyJ...", "token_type": "Bearer", "expires_in": 3600 }

Use this token in the Authorization header for all admin requests. The token is scoped to one application.

Keep the client_secret server-side only. Never expose it in browser code or client-side bundles. Use the publishableKey (cli_xxxx) for SDK calls from the browser.

Response envelope

All endpoints return a consistent JSON envelope:

{ "ok": true, "data": { ... } }           // success
{ "ok": false, "error": { "code": "...", "message": "..." } }  // error

Users

Create user

POST /v1/users

Pre-registers a user in your application before they register a passkey. Useful for seeding users from an existing system.

Supports idempotency: pass Idempotency-Key: <uuid> to safely retry without creating duplicates.

Request:

curl -X POST https://api.trymellonauth.com/v1/users \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a1b2c3d4-..." \
  -d '{ "external_user_id": "user_123" }'

Body:

Response 201:

{
  "ok": true,
  "data": {
    "external_user_id": "user_123",
    "created_at": "2026-04-07T12:00:00Z",
    "updated_at": "2026-04-07T12:00:00Z"
  }
}

Get user

GET /v1/users/:external_user_id

Response 200:

{
  "ok": true,
  "data": {
    "id": "uuid",
    "external_user_id": "user_123",
    "status": "active",
    "created_at": "2026-04-07T12:00:00Z",
    "updated_at": "2026-04-07T12:00:00Z"
  }
}

Returns 404 if the user does not exist.

List users

GET /v1/users

Cursor-based pagination.

Query parameters:

Response 200:

{
  "ok": true,
  "data": {
    "data": [
      { "id": "uuid", "external_user_id": "user_123", "status": "active", "created_at": "..." }
    ],
    "has_more": true,
    "next_cursor": "uuid-of-last-item"
  }
}

Delete user

DELETE /v1/users/:external_user_id

Deletes the user and cascades to all their passkeys, sessions, and audit log entries. This operation is irreversible.

Response 204: No content on success.

Credentials (Passkeys)

List credentials for a user

GET /v1/users/:external_user_id/credentials

Returns all passkeys registered by the user, with status and device information.

Query parameters:

Response 200:

{
  "ok": true,
  "data": {
    "credentials": [
      {
        "credential_id": "cred_abc123",
        "status": "active",
        "alias": "Touch ID — iPhone 15",
        "transports": ["internal"],
        "attestation_type": "none",
        "created_at": "2026-04-01T10:00:00Z",
        "last_used_at": "2026-04-07T08:30:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 1 }
  }
}

Credential statuses: active, revoked.

Revoke a credential

DELETE /v1/users/:external_user_id/credentials/:credential_id

Revokes a specific passkey. The user will not be able to authenticate with it. Other passkeys registered by the user remain active.

Use this when a user reports a lost device or suspects a compromised authenticator.

Response 204: No content on success.

curl -X DELETE \
  "https://api.trymellonauth.com/v1/users/user_123/credentials/cred_abc123" \
  -H "Authorization: Bearer <token>"

Audit Logs

List audit logs

GET /v1/audit-logs

Returns a paginated stream of security events for your application.

Query parameters:

Event types:

Response 200:

{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "uuid",
        "event": "auth.success",
        "success": true,
        "user_id": "uuid",
        "ip_address": "203.0.113.42",
        "metadata": {},
        "created_at": "2026-04-07T09:15:00Z"
      }
    ],
    "has_more": false,
    "next_cursor": null
  }
}

Retention by plan: Starter and Growth — 90 days. Scale and Enterprise — 1 year+. Logs beyond the retention window are automatically purged. Contact support for extended retention options.

Usage

Get usage

GET /v1/usage?period=YYYY-MM

Returns API call counts and active user counts for a billing period.

Query parameters:

Response 200:

{
  "ok": true,
  "data": {
    "tenant_id": "uuid",
    "period": "2026-04",
    "api_calls": 4820,
    "active_users": 312
  }
}

Privacy / GDPR

Get user data report

GET /v1/privacy/user-data/:external_user_id

Returns all data stored by TryMellon for a specific user. Use this to fulfill GDPR Article 15 (right of access) requests.

The report includes: user profile, registered credentials, session history, and audit log entries.

curl "https://api.trymellonauth.com/v1/privacy/user-data/user_123" \
  -H "Authorization: Bearer <token>"

To delete all data for a user (GDPR Article 17 — right to erasure), use Delete user. Deletion cascades to all associated data.

Rate limits

Admin endpoints are rate-limited per OAuth2 token. On exceeding the limit, the API returns 429 Too Many Requests with a Retry-After header. The SDK’s retry logic handles 429 with exponential backoff automatically; for raw HTTP clients, respect the Retry-After value.