Authentication API

Overview

User authentication and token management endpoints. For user registration, see Profiles API.

Endpoints

Login

POST /api/auth/login

Authenticate with email/password and receive an access token.

Authentication: Not required

Request:

{
  "idTag": "alice@example.com",
  "password": "secure-password"
}

Response:

{
  "data": {
    "tnId": 12345,
    "idTag": "alice@example.com",
    "name": "Alice Johnson",
    "token": "eyJhbGc...",
    "roles": ["user"],
    "profilePic": "b1~abc123",
    "settings": [["theme", "dark"], ["lang", "en"]],
    "swEncryptionKey": "base64url-encoded-key"
  },
  "time": "2025-01-01T12:00:00Z"
}
Field Type Description
tnId number Tenant ID
idTag string User identity tag
name string Display name
token string JWT access token
roles string[] User roles (e.g., user, SADM)
profilePic string Profile picture file ID
settings [string, string][] User settings as key-value pairs
swEncryptionKey string Service worker encryption key for push notifications (optional)

Combined Login Init

POST /api/auth/login-init

Combined login initialization that returns all available authentication methods in a single request. If the user already has a valid token, returns the authenticated session directly.

Authentication: Optional

Response (unauthenticated):

{
  "data": {
    "status": "unauthenticated",
    "qrLogin": {
      "sessionId": "session_abc123",
      "secret": "base64-secret"
    },
    "webAuthn": {
      "challenge": "base64-encoded-challenge",
      "rpId": "example.com",
      "allowCredentials": [...]
    }
  },
  "time": "2025-01-01T12:00:00Z"
}

Response (already authenticated):

{
  "data": {
    "status": "authenticated",
    "login": {
      "tnId": 12345,
      "idTag": "alice@example.com",
      "token": "eyJhbGc..."
    }
  },
  "time": "2025-01-01T12:00:00Z"
}

Logout

POST /api/auth/logout

Invalidate the current session.

Authentication: Required

Change Password

POST /api/auth/password

Change the authenticated user’s password.

Authentication: Required

Request:

{
  "currentPassword": "current-password",
  "newPassword": "new-secure-password"
}

Response:

{
  "data": {
    "success": true
  },
  "time": "2025-01-01T12:00:00Z"
}

Set Password

POST /api/auth/set-password

Set a new password using a reset token. Used during password recovery flow.

Authentication: Not required

Request:

{
  "token": "reset-token-from-email",
  "password": "new-secure-password"
}

Response:

{
  "data": {
    "success": true
  },
  "time": "2025-01-01T12:00:00Z"
}

Forgot Password

POST /api/auth/forgot-password

Request a password reset email.

Authentication: Not required

Request:

{
  "idTag": "alice@example.com"
}

Response:

{
  "data": {
    "sent": true
  },
  "time": "2025-01-01T12:00:00Z"
}

Refresh Login Token

GET /api/auth/login-token

Refresh the authentication token before it expires.

Authentication: Not required (uses existing valid token)

Response:

{
  "data": {
    "token": "eyJhbGc...",
    "expiresAt": 1735086400
  },
  "time": "2025-01-01T12:00:00Z"
}

Get Access Token

GET /api/auth/access-token

Exchange credentials or tokens for a scoped access token. Supports multiple authentication methods.

Authentication: Not required

Query Parameters:

  • token - Existing token to exchange
  • refId - Reference ID for share links
  • apiKey - API key for programmatic access
  • scope - Requested scope (optional)
  • refresh - Set to true to refresh an existing token

Response:

{
  "data": {
    "token": "eyJhbGc...",
    "expiresAt": 1735086400,
    "scope": "read:files"
  },
  "time": "2025-01-01T12:00:00Z"
}

Get Proxy Token

GET /api/auth/proxy-token

Get a proxy token for accessing remote resources via federation.

Authentication: Required

Query Parameters:

  • target - Target identity for federation

Response:

{
  "data": {
    "token": "eyJhbGc...",
    "expiresAt": 1735555555
  },
  "time": "2025-01-01T12:00:00Z"
}

QR Code Login

QR code login allows users to authenticate on a desktop browser by scanning a QR code with their mobile device.

Initialize QR Login

POST /api/auth/qr-login/init

Start a QR login session. The returned sessionId is encoded in the QR code, while the secret is kept by the initiating client for verification.

Authentication: Not required

Response:

{
  "data": {
    "sessionId": "session_abc123",
    "secret": "base64-secret-key"
  },
  "time": "2025-01-01T12:00:00Z"
}

Poll QR Login Status

GET /api/auth/qr-login/{session_id}/status

Long-poll the QR login session for status changes. The request blocks until the status changes or the timeout expires.

Authentication: Not required

Path Parameters:

  • session_id - The session ID from the init response

Query Parameters:

  • timeout - Long-poll timeout in seconds (default: 15, max: 30)

Headers:

  • x-qr-secret - The secret from the init response (required for verification)

Response:

{
  "data": {
    "status": "approved",
    "login": {
      "tnId": 12345,
      "idTag": "alice@example.com",
      "token": "eyJhbGc...",
      "name": "Alice Johnson"
    }
  },
  "time": "2025-01-01T12:00:00Z"
}

Status Values:

Status Description
pending Waiting for mobile device to scan
approved User approved on mobile - login field included
denied User denied on mobile
expired Session timed out

Get QR Login Details

GET /api/auth/qr-login/{session_id}/details

Get the details of a QR login session. Called by the mobile device after scanning the QR code to display the login request to the user.

Authentication: Required

Path Parameters:

  • session_id - The session ID encoded in the QR code

Response:

{
  "data": {
    "sessionId": "session_abc123",
    "idTag": "alice@example.com",
    "name": "Alice Johnson"
  },
  "time": "2025-01-01T12:00:00Z"
}

Respond to QR Login

POST /api/auth/qr-login/{session_id}/respond

Approve or deny a QR login request from the mobile device.

Authentication: Required

Path Parameters:

  • session_id - The session ID from the QR code

Request:

{
  "approved": true
}
Field Type Required Description
approved boolean Yes Whether to approve or deny the login

Response:

{
  "data": {
    "status": "approved"
  },
  "time": "2025-01-01T12:00:00Z"
}

WebAuthn (Passkey) Authentication

WebAuthn enables passwordless authentication using passkeys (biometrics, security keys, etc.).

List Passkey Registrations

GET /api/auth/wa/reg

List all registered passkeys for the authenticated user.

Authentication: Required

Response:

{
  "data": [
    {
      "keyId": "abc123",
      "name": "MacBook Touch ID",
      "createdAt": "2025-01-01T12:00:00Z",
      "lastUsedAt": "2025-01-15T09:30:00Z"
    }
  ],
  "time": "2025-01-01T12:00:00Z"
}

Get Registration Challenge

GET /api/auth/wa/reg/challenge

Get a challenge for registering a new passkey.

Authentication: Required

Response:

{
  "data": {
    "challenge": "base64-encoded-challenge",
    "rpId": "example.com",
    "rpName": "Cloudillo",
    "userId": "base64-user-id",
    "userName": "alice@example.com"
  },
  "time": "2025-01-01T12:00:00Z"
}

Register Passkey

POST /api/auth/wa/reg

Complete passkey registration with the WebAuthn response.

Authentication: Required

Request:

{
  "name": "MacBook Touch ID",
  "credential": {
    "id": "credential-id",
    "rawId": "base64-raw-id",
    "response": {
      "clientDataJSON": "base64-client-data",
      "attestationObject": "base64-attestation"
    },
    "type": "public-key"
  }
}

Response:

{
  "data": {
    "keyId": "abc123",
    "name": "MacBook Touch ID",
    "createdAt": "2025-01-01T12:00:00Z"
  },
  "time": "2025-01-01T12:00:00Z"
}

Delete Passkey

DELETE /api/auth/wa/reg/{key_id}

Remove a registered passkey.

Authentication: Required

Path Parameters:

  • key_id - The passkey identifier to delete

Response:

{
  "data": "ok",
  "time": "2025-01-01T12:00:00Z"
}

Get Login Challenge

GET /api/auth/wa/login/challenge

Get a challenge for passkey authentication.

Authentication: Not required

Query Parameters:

  • idTag - User identity (optional, for usernameless flow)

Response:

{
  "data": {
    "challenge": "base64-encoded-challenge",
    "rpId": "example.com",
    "allowCredentials": [
      {
        "type": "public-key",
        "id": "credential-id"
      }
    ]
  },
  "time": "2025-01-01T12:00:00Z"
}

Login with Passkey

POST /api/auth/wa/login

Authenticate using a passkey.

Authentication: Not required

Request:

{
  "credential": {
    "id": "credential-id",
    "rawId": "base64-raw-id",
    "response": {
      "clientDataJSON": "base64-client-data",
      "authenticatorData": "base64-auth-data",
      "signature": "base64-signature"
    },
    "type": "public-key"
  }
}

Response:

{
  "data": {
    "tnId": 12345,
    "idTag": "alice@example.com",
    "name": "Alice Johnson",
    "token": "eyJhbGc...",
    "roles": ["user"]
  },
  "time": "2025-01-01T12:00:00Z"
}

API Key Management

API keys enable programmatic access without interactive login.

List API Keys

GET /api/auth/api-keys

List all API keys for the authenticated user.

Authentication: Required

Response:

{
  "data": [
    {
      "keyId": "key_abc123",
      "name": "CI/CD Pipeline",
      "scope": "read:files,write:files",
      "createdAt": "2025-01-01T12:00:00Z",
      "lastUsedAt": "2025-01-15T09:30:00Z",
      "expiresAt": "2026-01-01T12:00:00Z"
    }
  ],
  "time": "2025-01-01T12:00:00Z"
}

Create API Key

POST /api/auth/api-keys

Create a new API key.

Authentication: Required

Request:

{
  "name": "CI/CD Pipeline",
  "scope": "read:files,write:files",
  "expiresAt": "2026-01-01T12:00:00Z"
}

Response:

{
  "data": {
    "keyId": "key_abc123",
    "name": "CI/CD Pipeline",
    "key": "ck_live_abc123xyz...",
    "scope": "read:files,write:files",
    "createdAt": "2025-01-01T12:00:00Z",
    "expiresAt": "2026-01-01T12:00:00Z"
  },
  "time": "2025-01-01T12:00:00Z"
}
Warning

The key field is only returned once at creation. Store it securely.

Get API Key

GET /api/auth/api-keys/{key_id}

Get details of a specific API key.

Authentication: Required

Path Parameters:

  • key_id - The API key identifier

Response:

{
  "data": {
    "keyId": "key_abc123",
    "name": "CI/CD Pipeline",
    "scope": "read:files,write:files",
    "createdAt": "2025-01-01T12:00:00Z",
    "lastUsedAt": "2025-01-15T09:30:00Z",
    "expiresAt": "2026-01-01T12:00:00Z"
  },
  "time": "2025-01-01T12:00:00Z"
}

Update API Key

PATCH /api/auth/api-keys/{key_id}

Update an API key’s metadata.

Authentication: Required

Path Parameters:

  • key_id - The API key identifier

Request:

{
  "name": "Production Pipeline",
  "scope": "read:files"
}

Response:

{
  "data": {
    "keyId": "key_abc123",
    "name": "Production Pipeline",
    "scope": "read:files",
    "createdAt": "2025-01-01T12:00:00Z",
    "expiresAt": "2026-01-01T12:00:00Z"
  },
  "time": "2025-01-01T12:00:00Z"
}

Delete API Key

DELETE /api/auth/api-keys/{key_id}

Revoke and delete an API key.

Authentication: Required

Path Parameters:

  • key_id - The API key identifier

Response:

{
  "data": "ok",
  "time": "2025-01-01T12:00:00Z"
}

Public Endpoints

Get Tenant Profile (Public)

GET /api/me
GET /api/me/full

Get the tenant (server) profile with public keys. This is a public endpoint that returns the server’s identity information.

Note: Both paths return the same data; /full is an alias for compatibility.

Authentication: Not required

Response:

{
  "data": {
    "idTag": "server@example.com",
    "name": "Example Server",
    "publicKey": "-----BEGIN PUBLIC KEY-----...",
    "serverInfo": {
      "version": "1.0.0",
      "features": ["federation", "crdt", "rtdb"]
    }
  },
  "time": "2025-01-01T12:00:00Z"
}

Resolve Identity Tag

GET /.well-known/cloudillo/id-tag

Resolve a domain-based identity to a Cloudillo server. This is part of the DNS-based identity system.

Authentication: Not required

Query Parameters:

  • idTag - The identity to resolve (e.g., alice@example.com)

Response:

{
  "data": {
    "idTag": "alice@example.com",
    "serverUrl": "https://cloudillo.example.com",
    "publicKey": "-----BEGIN PUBLIC KEY-----..."
  },
  "time": "2025-01-01T12:00:00Z"
}

Get VAPID Public Key

GET /api/auth/vapid

Get the VAPID public key for push notification subscriptions.

Authentication: Required

Response:

{
  "data": {
    "publicKey": "BNxwfD..."
  },
  "time": "2025-01-01T12:00:00Z"
}

See Also