Authentication

CorePlexML uses session cookies for web UI access and Bearer tokens (API keys) for programmatic access. Public endpoints that do not require authentication are: POST /api/auth/register, POST /api/auth/login, POST /api/auth/forgot-password, POST /api/auth/reset-password, and GET /api/auth/verify-email.

Important

API key management endpoints (/api/auth/api-keys*) require cookie session authentication. They do not accept Bearer API keys. For cookie-authenticated POST/PUT/PATCH/DELETE requests, include X-CSRF-Token with the value from the csrf_token cookie.

Register User 

POST /api/auth/register

Create a new user account.

Request Body

Field	Type	Required	Description
`email`	string	Yes	Valid email address.
`name`	string	Yes	Display name.
`password`	string	Yes	Minimum 8 characters.

Example

curl -X POST "$BASE_URL/api/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "name": "Alice Chen",
    "password": "s3cure!Pass"
  }'

import requests

resp = requests.post(f"{BASE_URL}/api/auth/register", json={
    "email": "alice@example.com",
    "name": "Alice Chen",
    "password": "s3cure!Pass",
})
print(resp.json())

Response 201 Created

{
  "user": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email": "alice@example.com",
    "name": "Alice Chen"
  },
  "verification_required": true
}

New accounts must verify email before they can log in.

Login 

POST /api/auth/login

Authenticate and receive a session cookie.

Request Body

Field	Type	Required	Description
`email`	string	Yes	Registered email.
`password`	string	Yes	Account password.
`remember`	boolean	No	Extend session duration (default `false`).

Example

curl -X POST "$BASE_URL/api/auth/login" \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "email": "alice@example.com",
    "password": "s3cure!Pass"
  }'

session = requests.Session()
resp = session.post(f"{BASE_URL}/api/auth/login", json={
    "email": "alice@example.com",
    "password": "s3cure!Pass",
})
# session object now carries the cookie for subsequent requests

Response 200 OK

{
  "user": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email": "alice@example.com",
    "name": "Alice Chen"
  }
}

The response also sets an HttpOnly session cookie.

If the email is not verified, login returns 403 with detail: Email not verified. Please check your inbox for the activation link..

Logout 

POST /api/auth/logout

Revoke the current session.

Example

curl -X POST "$BASE_URL/api/auth/logout" \
  -b cookies.txt

Response 200 OK

{
  "ok": true
}

Get Current User 

GET /api/auth/me

Return profile information for the authenticated user.

Example

curl "$BASE_URL/api/auth/me" \
  -H "Authorization: Bearer YOUR_API_KEY"

resp = requests.get(f"{BASE_URL}/api/auth/me", headers={
    "Authorization": "Bearer YOUR_API_KEY",
})
user = resp.json()

Response 200 OK

{
  "user": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email": "alice@example.com",
    "name": "Alice Chen",
    "is_superuser": false,
    "email_verified_at": "2026-01-15T10:30:00Z"
  }
}

Create API Key 

POST /api/auth/api-keys

Generate a new API key for programmatic access. The secret is returned only once in the response – store it securely.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Human-readable label for the key.
`scopes`	array[string]	No	Permissions: `read`, `write`, `predict`, `admin`. Default: all.

Example

# Requires a cookie-authenticated session and CSRF token
curl -X POST "$BASE_URL/api/auth/api-keys" \
  -b cookies.txt \
  -H "X-CSRF-Token: <csrf_token_cookie_value>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI Pipeline Key",
    "scopes": ["*"]
  }'

csrf = session.cookies.get("csrf_token")
resp = session.post(f"{BASE_URL}/api/auth/api-keys", headers={
    "X-CSRF-Token": csrf,
}, json={
    "name": "CI Pipeline Key",
    "scopes": ["*"],
})
key_data = resp.json()
print("Save this key:", key_data["api_key"])

Response 201 Created

{
  "prefix": "cp_a1b2c3d4",
  "api_key": "cp_a1b2c3d4.<secret>",
  "scopes": ["*"]
}

Warning

The key field is shown only in this response. If lost you must revoke the key and create a new one.

List API Keys 

GET /api/auth/api-keys

Return all API keys for the current user. The secret portion of each key is not included.

Example

curl "$BASE_URL/api/auth/api-keys" \
  -b cookies.txt

Response 200 OK

[
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "CI Pipeline Key",
    "prefix": "cp_a1b2c3d4",
    "scopes": ["*"],
    "last_used_at": "2026-02-28T18:45:00Z",
    "created_at": "2026-02-28T14:00:00Z"
  }
]

Revoke API Key 

POST /api/auth/api-keys/{key_id}/revoke

Permanently revoke an API key. Subsequent requests using that key will return 401 Unauthorized.

Path Parameters

Parameter	Type	Description
`key_id`	UUID	The ID of the API key to revoke.

Example

curl -X POST "$BASE_URL/api/auth/api-keys/b2c3d4e5-f6a7-8901-bcde-f12345678901/revoke" \
  -b cookies.txt \
  -H "X-CSRF-Token: <csrf_token_cookie_value>"

Response 200 OK

{
  "ok": true
}

Forgot Password 

POST /api/auth/forgot-password

Request a password reset email. Always returns 200 regardless of whether the email exists to prevent account enumeration.

Request Body

Field	Type	Required	Description
`email`	string	Yes	The email address associated with the account.

Example

curl -X POST "$BASE_URL/api/auth/forgot-password" \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com"}'

Response 200 OK

{
  "ok": true
}

Reset Password 

POST /api/auth/reset-password

Set a new password using a reset token received by email.

Request Body

Field	Type	Required	Description
`token`	string	Yes	Reset token from the email link (minimum 10 characters).
`password`	string	Yes	New password (minimum 8 characters).

Example

curl -X POST "$BASE_URL/api/auth/reset-password" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "abc123def456ghi789jkl012mno345",
    "password": "newS3cure!Pass"
  }'

Response 200 OK

{
  "ok": true
}