Clients API

Manage OIDC clients. Each client belongs to an organization and an application.

Base path: /api/admin/clients

Each client is an organization-specific registration connected to one deployment-global application; the application itself is not tenant-owned. See the Core ownership model.

Create Client

POST /api/admin/clients

Field	Type	Required	Description
client_name	string	✅	Human-readable client name
organization_id	uuid	✅	Owning organization
application_id	uuid	✅	Associated application
client_type	string	✅	confidential or public
application_type	string		web, native, or spa (default: web)
redirect_uris	string[]	✅	Allowed redirect URIs
grant_types	string[]		Grant types (defaults based on client type)
response_types	string[]		Response types
scope	string		Space-separated scopes
token_endpoint_auth_method	string		client_secret_post or none
cors_origins	string[]		Allowed CORS origins (for SPAs)
require_pkce	boolean		Require PKCE (default: true for public clients)
require_consent	boolean		Show the OIDC consent page for this client (default: false)
login_methods	string[]		Override org default login methods

{
  "client_name": "ERP Web App",
  "organization_id": "org-uuid",
  "application_id": "app-uuid",
  "client_type": "public",
  "application_type": "spa",
  "redirect_uris": ["https://erp.example.com/callback"],
  "scope": "openid profile email roles custom_claims",
  "cors_origins": ["https://erp.example.com"]
}

Response: 201 Created — Returns the client object with the generated client_id. For confidential clients, the initial secret is included in the response (shown only once).

List Clients

GET /api/admin/clients

Supports page, pageSize, search, status, sort, order, and organization_id filter.

Response: 200 OK — Paginated list with effectiveLoginMethods computed for each client.

Get Client

GET /api/admin/clients/:id

Response: 200 OK — Full client object including effectiveLoginMethods.

Update Client

PUT /api/admin/clients/:id

Updatable fields: client_name, redirect_uris, grant_types, response_types, scope, cors_origins, require_pkce, require_consent, login_methods.

Response: 204 No Content

Status Management

POST /api/admin/clients/:id/activate
POST /api/admin/clients/:id/deactivate

Response: 200 OK

Delete Client

DELETE /api/admin/clients/:id

Permanently deletes the client and its secrets. Its server-backed protocol authority and affected sessions are revoked.

Permission: admin:client:delete

Response: 204 No Content

Client Secrets

Confidential clients can have multiple active secrets for zero-downtime rotation.

Generate Secret

POST /api/admin/clients/:id/secrets

Field	Type	Description
label	string	Optional label for the secret

Response: 201 Created

{
  "id": "secret-uuid",
  "clientId": "client-uuid",
  "label": "production-2024",
  "secret": "the-plaintext-secret",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

DANGER

The plaintext secret is shown only once in this response. Store it securely.

List Secrets

GET /api/admin/clients/:id/secrets

Returns metadata only (no plaintext secrets).

Revoke Secret

POST /api/admin/clients/:id/secrets/:secretId/revoke

Response: 200 OK