Guides

Managing applications

Create and configure OAuth 2.1 client applications via the admin API.

Managing applications

Every OAuth 2.1 client you integrate with Auth Service is represented as an application record in the database. Applications hold the OIDC client configuration — redirect URIs, allowed scopes, MFA policy, and registration settings.

All application endpoints require an active session with the admin or superadmin role. Requests without a valid session cookie receive 401 AUTH_001.

Create an application

POST /api/admin/applications
Content-Type: application/json

{
  "name": "My App",
  "slug": "my-app",
  "description": "Optional description",
  "redirectUris": ["https://app.example.com/callback"],
  "allowedScopes": ["openid", "profile", "email", "roles", "permissions", "features"],
  "isActive": true,
  "skipConsent": false,
  "isMfaRequired": false,
  "allowRegister": true,
  "url": "https://app.example.com",
  "icon": "https://app.example.com/icon.png"
}

Field	Type	Default	Description
`name`	string	required	Display name (1–100 chars)
`slug`	string	required	URL-safe identifier used as `client_id` (lowercase alphanumeric + hyphens, 1–64 chars)
`description`	string	—	Optional description (max 500 chars)
`redirectUris`	string	`[]`	Allowed redirect URIs for the OAuth flow
`allowedScopes`	string	`["openid","profile","email"]`	Scopes this application may request
`isActive`	boolean	`true`	Whether the application accepts new authorizations
`skipConsent`	boolean	`false`	Skip the consent screen for trusted first-party apps
`isMfaRequired`	boolean	`false`	Block token issuance for users without MFA enabled
`allowRegister`	boolean	`true`	Whether the login page shows a registration link
`url`	string	—	Application home URL (displayed in admin)
`icon`	string	—	Icon URL (displayed in admin and consent screen)

The response includes the auto-generated clientId (same as slug) and clientSecret. The secret is shown only once — store it immediately.

List applications

GET /api/admin/applications

Returns all applications with their OAuth client metadata, roles, active user count, and plan summary.

Get a single application

GET /api/admin/applications/:id

Update an application

PATCH /api/admin/applications/:id
Content-Type: application/json

{
  "isMfaRequired": true,
  "skipConsent": true
}

All fields from the create schema are accepted, except slug (immutable after creation).

Rotate the client secret

POST /api/admin/applications/:id/rotate-secret

Generates a new random clientSecret, hashes it with SHA-256, and stores the hash. The plaintext secret is returned once in the response. All existing sessions using the old secret will fail at the next token refresh.

Delete an application

DELETE /api/admin/applications/:id

Returns 409 APP_004 if any users still have an active userApplications record for this application. Remove user access first.

Grant a user access to an application

POST /api/admin/applications/:id/users
Content-Type: application/json

{
  "userId": "<uuid>",
  "roleId": "<uuid>"   // optional — assigns a role immediately
}

If a default subscription plan exists for the application, it is assigned automatically.

Update a user's access record

PATCH /api/admin/applications/:id/users/:userId
Content-Type: application/json

{
  "isActive": false,
  "roleId": "<uuid>",
  "subscriptionPlanId": "<uuid>"
}

Revoke a user's access

DELETE /api/admin/applications/:id/users/:userId

Edit this pageorReport an issue

Quick start

Start the dev server, create your first application, and perform an OAuth 2.1 authorization flow.

Roles and permissions

Define per-application roles and permissions, assign them to users, and consume them in tokens.