Applications

An application in auth-service is an OAuth 2.0 client registration combined with an access policy, an RBAC model, and subscription plans. Every application has a unique slug that doubles as its OAuth client_id.

Application schema

enableEndSession, postLogoutRedirectUris and the two back-channel fields are stored on the BetterAuth OAuth client record and merged into every application payload returned by the admin API.

Machine scopes

A confidential application can use the client_credentials grant. The scopes it may request are set apart from the application fields, through PUT /api/admin/applications/:id/machine-scopes (superadmin only): m2m (default), wallet:read, wallet:debit and billing:read. The two wallet scopes let a machine client read and debit any user's wallet, which is why they are not part of the regular update. billing:read gives read access to the subscription, usage and invoices of users of the calling application (/api/app/billing/*). Removing a scope revokes the client's existing tokens. Public applications cannot use this grant.

Public vs confidential clients

PKCE (code_challenge / code_verifier, method S256) is required on every authorization request, for public and confidential clients alike.

When isPublic is true:

• No client secret is generated.
• token_endpoint_auth_method is set to none in the OAuth client record.
• The client is limited to the authorization_code and refresh_token grants.

When isPublic is false (default):

• A random 32-byte hex secret is generated at creation time.
• The secret is stored hashed (SHA-256 base64url) and returned once in the creation response.
• The client authenticates at the token endpoint with HTTP Basic (client_secret_basic) by default, or with the secret in the form body (client_secret_post) when the instance sets TOKEN_ENDPOINT_AUTH_METHOD=post (see Compatibility profiles). The grants are authorization_code, refresh_token and client_credentials.

Bootstrap macros

When a new application is created via POST /api/admin/applications, auth-service automatically:

1. Creates two default roles: user (default) and admin.
2. Creates a default free subscription plan.
3. Assigns all existing superadmin users to the application with the admin role and the free plan.
4. Assigns the caller who created the application with the admin role and the free plan, so an admin keeps access to the application it just created. A superadmin caller is covered by step 3 and is never attached twice.

Admin API endpoints

All application management endpoints require an admin or superadmin session.

List applications

GET /api/admin/applications

Returns all applications ordered by creation date, system applications included (the admin interface hides them unless "Show system applications" is on). Each application also carries enableEndSession, postLogoutRedirectUris, backchannelLogoutUri and backchannelLogoutSessionRequired.

{
  "applications": [
    {
      "id": "...",
      "name": "My App",
      "slug": "my-app",
      "isActive": true,
      "isPublic": false,
      ...
    }
  ]
}

Create an application

POST /api/admin/applications

{
  "name": "My App",
  "slug": "my-app",
  "description": "Optional description",
  "isPublic": false,
  "allowedScopes": ["openid", "profile", "email", "roles"],
  "redirectUris": ["https://app.example.com/callback"]
}

The response (201) is { application, clientId, clientSecret }. clientSecret contains the plaintext secret and is absent for public applications. Store it immediately — it cannot be retrieved afterwards. A duplicate slug is refused with APP_003.

Get an application

GET /api/admin/applications/:id

Update an application

PATCH /api/admin/applications/:id

All fields except slug and isPublic can be updated. name, allowedScopes, skipConsent, redirectUris, isActive, enableEndSession, postLogoutRedirectUris, backchannelLogoutUri and backchannelLogoutSessionRequired are mirrored onto the underlying BetterAuth oauthClient record. Changing isSystem requires a superadmin (AUTH_011 otherwise).

Delete an application

DELETE /api/admin/applications/:id

System applications cannot be deleted (APP_007). Otherwise the application is removed and responds 204: its dependent records (roles, permissions, plans, user access, consumption data) are cascade-deleted, its OAuth client and protected-resource links are removed, and its Stripe catalogue is archived rather than deleted. The delete route does not check for active subscriptions (the APP_004 code is defined in the registry but never raised).

Rotate client secret

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

Generates a new random secret, hashes it, stores it, and returns { clientSecret } once. The old secret is invalidated immediately and every token issued to the client is revoked. Public applications are refused (APP_001).

Managing user access

Grant access to a user

POST /api/admin/applications/:id/users

{
  "userId": "...",
  "roleId": "...",
  "subscriptionPlanId": "...",
  "reason": "..."
}

roleId, subscriptionPlanId and reason are optional. Without roleId the application's default role is assigned; without subscriptionPlanId its default plan is assigned. Answers 201 { ok: true }. POST /api/admin/applications/:id/users/bulk grants many users at once (an organizationId or a list of userIds).

List users with access

GET /api/admin/applications/:id/users

Update a user's access

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

{
  "isActive": true,
  "roleId": "...",
  "subscriptionPlanId": "..."
}

expiresAt and reason are also accepted; reason is required when subscriptionPlanId or expiresAt is present. roleId replaces every role the user holds in the application (null removes them). Setting isActive to false also revokes the user's OAuth tokens for this application.

Revoke access

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

Revokes the user's OAuth tokens for the application, then deletes the user's roles, subscription, consumption data and access record for it. Answers 204.