Authentication API

Authentication API

User authentication and token management endpoints.

Endpoints

Register

POST /api/auth/register

Register a new user account. This initiates the registration process and sends a verification email.

Request:

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

Response:

{
  "data": {
    "tnId": 12345,
    "idTag": "alice@example.com",
    "name": "Alice Johnson",
    "token": "eyJhbGc..."
  }
}

Verify Registration

POST /api/auth/register-verify

Complete email verification after registration.

Request:

{
  "idTag": "alice@example.com",
  "code": "123456"
}

Response:

{
  "data": {
    "tnId": 12345,
    "idTag": "alice@example.com",
    "name": "Alice Johnson",
    "token": "eyJhbGc...",
    "verified": true
  },
  "time": 1735000000,
  "reqId": "req_abc123"
}

Login

POST /api/auth/login

Authenticate and receive an access token.

Request:

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

Response:

{
  "data": {
    "tnId": 12345,
    "idTag": "alice@example.com",
    "name": "Alice Johnson",
    "token": "eyJhbGc...",
    "roles": ["user"]
  }
}

Logout

POST /api/auth/logout

Invalidate the current session.

Authentication: Required

Change Password

POST /api/auth/password

Change the user’s password.

Authentication: Required

Request:

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

Response:

{
  "data": {
    "success": true
  },
  "time": 1735000000,
  "reqId": "req_abc123"
}

Refresh Login Token

GET /api/auth/login-token

Refresh the authentication token before it expires.

Authentication: Required

Response:

{
  "data": {
    "token": "eyJhbGc...",
    "expiresAt": 1735086400
  },
  "time": 1735000000,
  "reqId": "req_abc123"
}

Get Access Token

GET /api/auth/access-token

Exchange credentials for a scoped access token.

Query Parameters:

  • idTag - User identity
  • password - User password
  • roles - Requested roles (optional)
  • ttl - Token lifetime in seconds (optional)

Get Proxy Token

GET /api/auth/proxy-token

Get a proxy token for accessing remote resources.

Authentication: Required

Query Parameters:

  • target - Target identity for federation

Response:

{
  "data": {
    "token": "eyJhbGc...",
    "expiresAt": 1735555555
  }
}

Get Current User (Public)

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

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

Note: All three paths return the same data; /keys and /full are aliases 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": 1735000000,
  "reqId": "req_abc123"
}

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": 1735000000,
  "reqId": "req_abc123"
}

See Also