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"]
  },
  "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"
}

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