public API
Reference for the public endpoint group — 4 endpoints.
Generated from the live OpenAPI spec. Re-run _generate_api_reference.py after backend changes.
Authentication#
All endpoints require a Bearer JWT in the Authorization header unless noted otherwise. See Concepts → Tokens and scopes and Reference → OAuth endpoints for how to obtain one.
Endpoints#
POST /api/v1/public/register/applications#
Submit application registration request
Submit a registration request for an external application.
This is a public endpoint that does not require authentication. Rate limited to prevent abuse.
Flow:
- Submit this request with your application details
- Save the
request_idandstatus_tokenfrom the response - Use the status endpoint to check for updates
- Once approved, credentials will be available via the status endpoint
Important:
- The
status_tokenis only shown once - save it securely - You need both
request_idandstatus_tokento check status - Credentials are only retrievable once after approval
Request body:
Required.
application/json→SelfRegistrationRequest
Responses:
| Status | Body |
|---|---|
201 |
application/json → RegistrationResponse |
422 |
application/json → HTTPValidationError |
DELETE /api/v1/public/register/applications/{request_id}#
Cancel registration request
Cancel a pending registration request.
Requires the status_token that was provided when the request was submitted.
Only pending requests can be cancelled.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
request_id |
path | yes | string |
|
status_token |
query | yes | string |
Status token provided during registration |
Responses:
| Status | Body |
|---|---|
204 |
Successful Response |
422 |
application/json → HTTPValidationError |
GET /api/v1/public/register/applications/{request_id}/status#
Check registration status
Check the status of a registration request.
Requires the status_token that was provided when the request was submitted.
Status values:
PENDING: Request is awaiting reviewAPPROVED: Request approved - credentials available (one-time retrieval)REJECTED: Request rejected - see rejection_reasonCANCELLED: Request was cancelled
Credential retrieval:
When status is APPROVED and credentials have not been retrieved yet,
they will be included in the response. Credentials can only be retrieved once.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
request_id |
path | yes | string |
|
status_token |
query | yes | string |
Status token provided during registration |
Responses:
| Status | Body |
|---|---|
200 |
application/json → StatusResponse |
422 |
application/json → HTTPValidationError |
GET /api/v1/public/register/validate#
Validate registration target
Validate a registration target before submitting a registration request.
Options:
scope=global- Check if global registration is enabledtenant_slug- Validate a tenant slugpartner_slug- Validate a partner slug
Provide only one option.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
scope |
query | no | string | null |
Scope to validate: 'global' for global registrations |
tenant_slug |
query | no | string | null |
Tenant slug to validate |
partner_slug |
query | no | string | null |
Partner slug to validate |
Responses:
| Status | Body |
|---|---|
200 |
application/json → ValidateResponse |
422 |
application/json → HTTPValidationError |
Schemas#
Definitions for every type referenced by the endpoints above. Schema-to-schema references on this page link within the page; cross-page references would require visiting the linked page.
HTTPValidationError#
| Field | Type | Required | Description |
|---|---|---|---|
detail |
array of ValidationError |
no |
RegistrationResponse#
Response after submitting a registration request.
| Field | Type | Required | Description |
|---|---|---|---|
request_id |
string |
yes | Unique registration request ID |
status_token |
string |
yes | Secret token to check status (save this securely!) |
status |
string |
no | Current request status |
status_url |
string |
yes | URL to check registration status |
message |
string |
yes | Human-readable message |
SelfRegistrationRequest#
Self-registration request from an external application.
For tenant-scoped apps, use tenant_slug to identify the target tenant. For partner-scoped apps, use partner_slug. For global-scoped apps, set scope="GLOBAL" (no slug needed).
| Field | Type | Required | Description |
|---|---|---|---|
tenant_slug |
string | null |
no | Target tenant slug (for tenant-scoped apps) |
partner_slug |
string | null |
no | Target partner slug (for partner-scoped apps) |
scope |
string | null |
no | Application scope: GLOBAL, PARTNER, or TENANT. If not specified, inferred from slug. |
name |
string |
yes | Application name |
description |
string | null |
no | Brief description of the application |
application_type |
string |
yes | Application type: WEB, SPA, NATIVE, or SERVICE |
redirect_uris |
array of string |
yes | OAuth redirect URIs (at least one required) |
post_logout_redirect_uris |
array of string | null |
no | Post-logout redirect URIs |
allowed_origins |
array of string | null |
no | CORS allowed origins (for SPA apps) |
requested_scopes |
array of string |
no | Requested OAuth scopes |
grant_types |
array of string |
no | Requested OAuth grant types |
contact_email |
string (email) |
yes | Contact email for registration updates and credentials |
contact_name |
string | null |
no | Contact person name |
organization_name |
string | null |
no | Organization or company name |
website_url |
string | null |
no | Application or organization website |
StatusResponse#
Response when checking registration status.
| Field | Type | Required | Description |
|---|---|---|---|
request_id |
string |
yes | |
status |
string |
yes | PENDING, APPROVED, REJECTED, CANCELLED, or EXPIRED |
name |
string |
yes | |
submitted_at |
string |
yes | |
reviewed_at |
string | null |
no | |
expires_at |
string | null |
no | |
credentials |
object of string → string | null |
no | OAuth credentials (only if approved and not yet retrieved) |
rejection_reason |
string | null |
no | |
message |
string |
yes |
ValidateResponse#
Response from validation endpoint.
| Field | Type | Required | Description |
|---|---|---|---|
valid |
boolean |
yes | Whether the slug is valid |
name |
string | null |
no | Tenant/partner name if valid |
accepting_registrations |
boolean |
yes | Whether registrations are being accepted |
message |
string |
yes |
ValidationError#
| Field | Type | Required | Description |
|---|---|---|---|
loc |
array of string | integer |
yes | |
msg |
string |
yes | |
type |
string |
yes |