Auth API
Authentication API for Celerp users, login, logout, password recovery, company switching, and API access.
Generated from the Celerp 2.5.0 OpenAPI schema, 21 September 2026.
POST /auth/api-key
Create API Key
Create an API key for the authenticated user.
Responses
| Status | Description | Body |
|---|---|---|
200 | Returns the created API key or creation result. | object |
Example
curl -X POST http://localhost:8000/auth/api-key \
-H "Authorization: Bearer $TOKEN"GET /auth/bootstrap-status
Get Initial Setup Status
Return whether initial Celerp setup has been completed, allowing clients to choose between first-time registration and the normal sign-in flow.
Responses
| Status | Description | Body |
|---|---|---|
200 | Returns the requested initial setup status result. | object |
Example
curl -X GET http://localhost:8000/auth/bootstrap-status \
-H "Authorization: Bearer $TOKEN"POST /auth/change-password
Change User Password
Change the password for the authenticated Celerp user after validating the supplied current password.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
current_password | string | yes | User's current password, required to authorize a password change. |
new_password | string | yes | New password to set for the user. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Returns a confirmation message. | object |
422 | The request failed validation. The response lists each invalid field and why. | HTTPValidationError |
Example
curl -X POST http://localhost:8000/auth/change-password \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ ... }'POST /auth/login
Log In
Authenticate a Celerp user.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
email | string | yes | Email address associated with the user, contact, or request. |
password | string | yes | Password supplied for authentication or initial user creation. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Returns the access and refresh tokens for the new session. | object |
422 | The request failed validation. The response lists each invalid field and why. | HTTPValidationError |
Example
curl -X POST http://localhost:8000/auth/login \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ ... }'POST /auth/login-force
Log In and Replace Existing Sessions
Authenticate a Celerp user while replacing the user's other active sessions, then return the new session information.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
email | string | yes | Email address associated with the user, contact, or request. |
password | string | yes | Password supplied for authentication or initial user creation. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Returns the access and refresh tokens for the new session. | object |
422 | The request failed validation. The response lists each invalid field and why. | HTTPValidationError |
Example
curl -X POST http://localhost:8000/auth/login-force \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ ... }'POST /auth/logout
Log Out
End the caller's current Celerp authentication session.
Request body
LogoutRequest, optional
Responses
| Status | Description | Body |
|---|---|---|
200 | Returns a confirmation message. | object |
422 | The request failed validation. The response lists each invalid field and why. | HTTPValidationError |
Example
curl -X POST http://localhost:8000/auth/logout \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ ... }'GET /auth/my-companies
List Accessible Companies
Return the companies the authenticated user can access, including the information needed to choose an active company.
Responses
| Status | Description | Body |
|---|---|---|
200 | Returns the requested accessible companies. | object |
Example
curl -X GET http://localhost:8000/auth/my-companies \
-H "Authorization: Bearer $TOKEN"POST /auth/password-reset/confirm
Confirm Password Reset
Set a new password using a valid password-reset request.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
token | string | yes | Opaque token supplied by the relevant password-reset, sharing, or public workflow. |
new_password | string | yes | New password to set for the user. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Returns a confirmation message. | object |
422 | The request failed validation. The response lists each invalid field and why. | HTTPValidationError |
Example
curl -X POST http://localhost:8000/auth/password-reset/confirm \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ ... }'POST /auth/password-reset/request
Request Password Reset
Request a password reset for the supplied email address. The response does not reveal whether the address belongs to an account.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
email | string | yes | Email address associated with the user, contact, or request. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Returns the same confirmation message whether or not the address has an account. | object |
422 | The request failed validation. The response lists each invalid field and why. | HTTPValidationError |
Example
curl -X POST http://localhost:8000/auth/password-reset/request \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ ... }'POST /auth/register
Register First Administrator
Create the first Celerp administrator and company during initial setup. Registration is available only before the installation has been bootstrapped.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
company_name | string | yes | Company or organization name. |
email | string | yes | Email address associated with the user, contact, or request. |
name | string | yes | Human-readable name for the record. |
password | string | yes | Password supplied for authentication or initial user creation. |
setup_code | string, optional | -- | Setup code used during supported first-time registration. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Returns the access and refresh tokens for the new administrator. | object |
422 | The request failed validation. The response lists each invalid field and why. | HTTPValidationError |
Example
curl -X POST http://localhost:8000/auth/register \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ ... }'POST /auth/switch-company/{company_id}
Switch Active Company
Switch the authenticated user's active company to another company they can access.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
company_id | path | yes | string | Identifier of the company. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Returns new access and refresh tokens scoped to the selected company. | object |
422 | The request failed validation. The response lists each invalid field and why. | HTTPValidationError |
Example
curl -X POST http://localhost:8000/auth/switch-company/:company_id \
-H "Authorization: Bearer $TOKEN"POST /auth/token/refresh
Refresh Authentication Session
Refresh the authenticated Celerp session.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
refresh_token | string | yes | Refresh credential used to renew the authenticated session. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Returns new access and refresh tokens. | object |
422 | The request failed validation. The response lists each invalid field and why. | HTTPValidationError |
Example
curl -X POST http://localhost:8000/auth/token/refresh \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ ... }'