API Documentation

Integrate your third-party services with Zarnian for seamless user authentication and access management.

Authentication Endpoints

Use these endpoints to allow users to register or log in to Zarnian from your service. These endpoints are an alternative to the main redirect-based SSO flow.

User Registration

POST /api/auth/external/register

Registers a new user in Zarnian.

Request Body (JSON)

{
  "name": "string (required)",
  "email": "string (required, valid email format)",
  "password": "string (required, min 6 characters)",
  "serviceRedirectUrl": "string (required, full URL of your service page)"
}

The serviceRedirectUrl must match one of the active service URLs configured in Zarnian.

Responses

Success (201 Created):

{
  "success": true,
  "message": "User registered successfully.",
  "user": {
    "uid": "string",
    "name": "string",
    "email": "string",
    "role": "User",
    "status": "active",
    "createdAt": "ISO_string_date",
    "enabledServices": [],
    "avatarUrl": "string"
  }
}

Error (400, 409, 500):

{
  "success": false,
  "error": "Error message detailing the issue (e.g., Email already in use, Invalid service URL, Password too weak)"
}

User Login

POST /api/auth/external/login

Logs in an existing user to Zarnian.

Request Body (JSON)

{
  "email": "string (required, valid email format)",
  "password": "string (required)",
  "serviceRedirectUrl": "string (required, full URL of your service page)"
}

The serviceRedirectUrl must match one of the active service URLs configured in Zarnian.

Responses

Success (200 OK):

{
  "success": true,
  "message": "Login successful.",
  "user": {
    "uid": "string",
    "name": "string",
    "email": "string",
    "role": "string",
    // ... other user fields
  }
}

Error (400, 401, 500):

{
  "success": false,
  "error": "Error message detailing the issue (e.g., Invalid email or password)"
}

Authentication Flow Recommendation

While these endpoints are available, the recommended authentication method is the Redirect-based SSO Flow, which is more secure as your service never has to handle user passwords.

Redirect users from your service to the Hub's login page (/auth/login).
After a successful login, the Hub redirects back to your service with a single-use authToken.
Your service exchanges this token for user data by calling the /api/auth/exchange-token endpoint.

This flow is demonstrated in the cloudflare-worker.js example file.