Application types

An “application” in auth-server is not one thing. There are two separate registries, they live in different tables, they are created through different endpoints, and they answer different questions:

	oauth_clients	m2m_clients
Answers	”Who is this person?"	"Which service is calling?”
Created by	An admin or any signed-in member	A system_admin, only
Endpoint	POST /admin/oauth/clients · POST /oidc/clients	POST /admin/m2m-clients
Grants	authorization_code, refresh_token, and — when an admin says so — client_credentials	client_credentials only
A user is present	Yes. The whole flow is a person signing in	No. There is no user at all
Token subject (sub)	The user’s UUID	The client id
Token shape	Normal user access token + an RS256 id_token	token_type: "service", no user fields
Migration	025 + 028	012

Both registries share one token endpoint, POST /oauth/token, because that is what OIDC discovery advertises. Which registry serves a request is decided by the client id: the OIDC handler looks the id up in oauth_clients first and hands anything it does not recognise to the m2m handler (routes.go, POST /oauth/token).

There is a third thing called an “app”, and it is not a client

apps (the app_code registry — see App registration) is a different concept again. An app is a first-party consumer identified by a code like marketplace-v2, which scopes a user’s permissions and user pool. An OAuth client is a relying party identified by a client_id. A client row may name an app through its app_code column, but they are not the same object and one does not imply the other. See Users, apps and tenancy.

I want to… → use…

I want to	Use	Notes
Add “Sign in with {Provider}” to a web app with a backend	oauth_clients, confidential (public: false)	Keeps a secret. authorization_code + PKCE + refresh_token.
Sign users into an SPA or mobile app	oauth_clients, public (public: true)	No secret exists to steal. PKCE is mandatory and is the only thing binding a code to you.
Let a cron job / CI runner / backend service call the API with no user	m2m_clients	client_credentials. Admin-only to create.
Give an existing interactive application a service identity too	oauth_clients with client_credentials added to grant_types	Admin-only. Confidential clients only. New — see below.
Ship a browser widget that reads public data	Neither — or a public client	A browser cannot hold a secret. If it needs the user, register a public client and use PKCE. If it does not, do not issue a credential at all.
Register my own application against someone else’s deployment	POST /oidc/clients (self-service)	Any signed-in member. Identity scopes only, max 10 per account.

The two ways to get an oauth_clients row

Same table, same runtime behaviour, very different capabilities at registration. The self-service surface can do strictly less, which is what makes it safe to open to every member.

	Admin (/admin/oauth/clients)	Self-service (/oidc/clients)
Who may call it	system_admin or super_admin	Any authenticated member
client_id	You choose it	The server mints it — name-slug + 6 random bytes
Scopes available	All 8, including civic:* and offline_access	openid, profile, email only
grant_types	Settable + validated	Fixed to authorization_code + refresh_token
trusted (skip consent)	Settable	Never
require_pkce	Settable	Forced true
app_code	Settable	Never
Volume cap	None	10 per account, 10 creates/hour
Owner	owner_user_id is NULL	The caller’s user id
Visible to the owner UI	No	Yes

The NULL owner is load-bearing, not incidental. Every self-service query carries owner_user_id = $caller inside the statement, and = $caller never matches NULL — so admin-created clients, including the trusted first-party one, are invisible and untouchable through the self-service endpoints without a single extra check (store_selfservice.go).

What changed recently

If you integrated before 2026-08, three things behave differently now.

grant_types is enforced — it used to be decoration

The column was written at registration and never read. There was no AllowsGrant; the token endpoint dispatched purely on the request’s own grant_type. Removing a grant from a client changed nothing at all.

It is now checked at both /oauth/authorize and /oauth/token (store.go Client.AllowsGrant). A client not registered for a grant gets unauthorized_client.

Existing clients are unaffected. An empty grant_types array means the default — authorization_code + refresh_token — not “nothing allowed”, precisely so that rows written before enforcement keep working (oidc.DefaultGrants).

refresh_token now works at /oauth/token

It was advertised in the discovery document and absent from the implementation. Anything that was not authorization_code fell through to the m2m handler, which serves only client_credentials and answered unsupported_grant_type. A client that did everything right — requested offline_access, stored the refresh token, came back when the access token expired — hit a flat refusal at the URL we told it to use.

RFC 6749 §6 is implemented now. See The grants → refresh_token.

client_credentials reaches oauth_clients too

The grant previously served only the separate m2m_clients registry, so an application created through the admin OIDC endpoint could never use it however its grant_types were set.

Now both registries share the endpoint and one rule: the grant works iff the client is registered for it. An admin must add client_credentials to grant_types, and the client must be confidential — a public client has no secret, and this grant is nothing but client authentication. Self-service clients still cannot get it, deliberately.

Read next

• Client properties — every column on oauth_clients, what it does, its default, and where it is enforced.
• Registering an application — the admin and self-service flows, with working curl.
• The grants — a worked example per grant.
• Scopes — all eight, and the two sensitive ones.
• Users, apps and tenancy — how an operator decides which users belong to which application, and what is not enforced.
• Redirect URIs — the exact-match rule the whole flow rests on.
• OIDC provider — the wire protocol: discovery, JWKS, id_token claims.