Applications API

Reference for the Applications endpoint group — 8 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#

GET /api/v1/admin/applications/#

List Applications

List applications based on admin's access level.

Visibility rules:

• Super admins: All applications
• Partner admins: Global apps + Partner apps for their partner + Tenant apps in their partner's tenants
• Tenant admins: Global apps + Partner apps for their parent partner + Tenant apps for their tenant

Parameters:

Responses:

POST /api/v1/admin/applications/#

Create Application

Create a new application (OAuth client).

Scope rules:

• Super admin: Can create any scope (GLOBAL, PARTNER, TENANT)
• Partner admin: Can create PARTNER (for their partner) or TENANT (for tenants in their partner)
• Tenant admin: Can only create TENANT scope for their tenant

Parameters:

Request body:

Required.

• application/json → object

Responses:

DELETE /api/v1/admin/applications/{application_id}#

Delete Application

Soft delete an application.

Parameters:

Responses:

GET /api/v1/admin/applications/{application_id}#

Get Application

Get an application by ID.

Parameters:

Responses:

PATCH /api/v1/admin/applications/{application_id}#

Update Application

Update an application.

Parameters:

Request body:

Required.

• application/json → object

Responses:

GET /api/v1/admin/applications/{application_id}/effective-groups#

Get Application Effective Groups

List the groups assigned to an application — the counterpart to effective-users.

effective-users resolves group entitlements down to individual users and discards which group granted access. This endpoint returns the assigned groups themselves, so a consumer can map its own group-based roles (e.g. "platform-admin = members of group X") to ScaiKey group ids at configuration time, rather than only per-request from a user's groups claim.

Authentication mirrors effective-users exactly:

• An application may list its own assigned groups using its ordinary client_credentials platform token — no admin scope required.
• Any other caller needs an admin principal with hierarchical access to the application (a platform token with admin:read/admin:write, or a user token whose role covers the app).

Only groups directly assigned to the application are returned (these are the entitlement-granting groups) — it never enumerates groups platform-wide. Soft-deleted groups are omitted. Results are confined to the application's scope (GLOBAL: all tenants; PARTNER: the partner's tenants; TENANT: that tenant), and an optional tenant_id narrows further. Each item carries the group id, name, description, group_type and its tenant (and partner) — the id being what group-based authorization models store.

Parameters:

Responses:

GET /api/v1/admin/applications/{application_id}/effective-users#

Get Application Effective Users

Get all users who have access to an application across all tenants.

This endpoint is designed for GLOBAL applications that need to sync users across all tenants. It returns users who have been assigned access either directly or via group membership.

Authentication (this returns cross-tenant data, so the accepted principals are narrow):

• An application may query its own effective users with its ordinary client_credentials platform token — no admin scope required.
• A super-admin-grade principal (a platform token with admin:read/ admin:write, or a user with a live super_admin role) may query any application.
• A partner/tenant admin may query only a PARTNER/TENANT application within their own hierarchy. They are not admitted to a GLOBAL application's data (that cross-tenant read is super-admin-grade). A non-admin user is always refused.

For GLOBAL apps: Returns users from all tenants For PARTNER apps: Returns users from all tenants in the partner For TENANT apps: Returns users from that tenant only

Response includes tenant information for each user to support multi-tenant sync.

Parameters:

Responses:

POST /api/v1/admin/applications/{application_id}/rotate-secret#

Rotate Application Secret

Rotate an application's client secret.

Parameters:

Responses:

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#

ValidationError#