API

API Documentation

This guide covers the core API endpoints for integrating the Cloudflare Auth Service into your applications.

The API is divided into two main sections:

1. Admin API: For managing the platform (projects, users, logs).
2. Auth API (Per-Project): For user authentication (login, register, OAuth).

Base URL

All API requests should be made to:

https://<your-worker-subdomain>.workers.dev

Or your custom domain if configured:

https://auth.yourdomain.com

Authentication

Admin API Authentication

Admin endpoints require an X-Admin-Session header with a valid session token obtained from /api/admin/login.

Project API Authentication

Project-specific endpoints (like /api/auth/:projectId/me) require a Bearer Token in the Authorization header:

Authorization: Bearer <your_access_token>

---

Auth API Reference (Per-Project)

These endpoints are used by your client applications (web, mobile, etc.) to authenticate users against a specific project. Replace :projectId with your project's ID (e.g., mobile_app).

Register User

Create a new user account.

POST /api/auth/:projectId/register

Request Body:

{
  "email": "user@example.com",
  "password": "strongpassword123",
  "displayName": "John Doe"
}

Response:

{
  "success": true,
  "data": {
    "user": {
      "id": "user_id_123",
      "email": "user@example.com",
      "displayName": "John Doe"
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "refresh_token_xyz..."
  }
}

Login

Authenticate an existing user.

POST /api/auth/:projectId/login

Request Body:

{
  "email": "user@example.com",
  "password": "strongpassword123"
}

Response:

{
  "success": true,
  "data": {
    "user": { ... },
    "accessToken": "...",
    "refreshToken": "..."
  }
}

Get Current User

Retrieve the authenticated user's profile.

GET /api/auth/:projectId/me

Headers:

Authorization: Bearer <access_token>

Response:

{
  "success": true,
  "data": {
    "id": "user_id_123",
    "email": "user@example.com",
    "displayName": "John Doe",
    "emailVerified": true,
    "createdAt": "2023-01-01T00:00:00Z"
  }
}

Refresh Token

Get a new access token using a refresh token.

POST /api/auth/:projectId/refresh

Request Body:

{
  "refreshToken": "refresh_token_xyz..."
}

Response:

{
  "success": true,
  "data": {
    "accessToken": "new_access_token...",
    "refreshToken": "new_refresh_token..." // (Optional, if rotated)
  }
}

---

Admin API Reference

These endpoints are for managing the authentication service itself.

Admin Login

POST /api/admin/login

Request Body:

{
  "email": "admin@example.com",
  "password": "password"
}

Response:

{
  "success": true,
  "data": {
    "sessionToken": "session_token_abc...",
    "admin": { ... }
  }
}

List Projects

GET /api/admin/projects

Headers:

X-Admin-Session: <session_token>

Response:

{
  "success": true,
  "data": [
    {
      "id": "mobile_app",
      "name": "Mobile App",
      "environment": "production",
      "enabled": true
    },
    ...
  ]
}

Create Project

POST /api/admin/projects

Request Body:

{
  "name": "New Project",
  "environment": "development",
  "description": "My new project"
}

Response:

{
  "success": true,
  "data": {
    "id": "new_project",
    ...
  }
}

---

Error Handling

The API uses standard HTTP status codes and returns error responses in the following format:

{
  "success": false,
  "error": "Error message description",
  "code": "ERROR_CODE" // Optional
}

Common Status Codes:

• 200 OK: Success
• 400 Bad Request: Invalid input (validation error)
• 401 Unauthorized: Invalid or missing token
• 403 Forbidden: Insufficient permissions
• 404 Not Found: Resource does not exist
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server-side issue