---
title: public API
path: reference/api/public
status: published
---

# 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](/docs/scaikey/concepts/tokens-and-scopes) and [Reference → OAuth endpoints](/docs/scaikey/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:**
1. Submit this request with your application details
2. Save the `request_id` and `status_token` from the response
3. Use the status endpoint to check for updates
4. Once approved, credentials will be available via the status endpoint

**Important:**
- The `status_token` is only shown once - save it securely
- You need both `request_id` and `status_token` to check status
- Credentials are only retrievable once after approval

**Request body:**

Required.

- `application/json` → [`SelfRegistrationRequest`](#schema-selfregistrationrequest)

**Responses:**

| Status | Body |
|---|---|
| `201` | `application/json` → [`RegistrationResponse`](#schema-registrationresponse) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-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`](#schema-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 review
- `APPROVED`: Request approved - credentials available (one-time retrieval)
- `REJECTED`: Request rejected - see rejection_reason
- `CANCELLED`: 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`](#schema-statusresponse) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-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 enabled
- `tenant_slug` - Validate a tenant slug
- `partner_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`](#schema-validateresponse) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-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`](#schema-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 |  |