Clients: How Applications Are Registered

Docs version v1 (main) · Nauthera is pre-1.0, in a design-partner program · Updated November 4, 2026

An OAuth client belongs to exactly one organization, decided when it is first registered and never moved by a later write. There are three ways to register one.

The server also provisions each organization's own admin console and machine clients. The admin API reports which of these a client came from as its source: operator (the control plane, which the operator and nauthera-cli use), dynamic or provisioner.

#With an OIDCClient manifest

The operator sends an OIDCClient's spec to the server over the gRPC control plane, writes the server's answer to the resource's status, and delivers a minted client secret into a Kubernetes Secret. spec.deletionPolicy decides what deleting the manifest does: under Retain, the default, the client stays registered and its Secret is released; under Delete the client is removed. The operator also notices when a client it manages was changed outside it. The resource is described in OIDCClient, and installing and connecting the operator in Operator.

#Through the AdminService

UpsertOIDCClient is a declarative, idempotent full replace with an etag for optimistic concurrency. When the spec asks for a secret (secret.generate), the server mints one, stores only its SHA-256 digest, and returns the plaintext once, in the response to the upsert that minted it. That is normally the upsert that created the client. An update that asks for a secret for a client that has none (a public client made confidential, for example) also mints one. Re-applying a spec never rotates the secret.

On a local stack, nauthera-cli drives the same RPC:

go run ./cmd/nauthera-cli create client my-app \
  --redirect-uri https://app.example.com/callback \
  --post-logout-redirect-uri https://app.example.com/ \
  --scopes openid,profile,email,offline_access \
  --grant-types authorization_code,refresh_token \
  --pkce required_s256

nauthera-cli connects with mutual TLS when given --tls-ca-file, --tls-cert-file and --tls-key-file; its certificate's identity must be listed in server.grpc.tls.allowed_clients with the clients operation, and organizations too to use --org. Without them it speaks plaintext gRPC, which the server accepts only with server.grpc.allow_insecure: true on a loopback address.

#Dynamic client registration

Dynamic registration is for clients that are not yours to declare, such as third-party software registering against your server. For your own applications on Kubernetes, prefer an OIDCClient manifest: see Operator or dynamic registration?.

POST /register implements RFC 7591. Each registration must present an initial access token: a bearer token for the target organization that carries the nauthera.clients:register scope. The response includes a registration_access_token and a registration_client_uri for RFC 7592 management. Store the token from the registration response: read and update responses do not return it again.

curl -s https://auth.example.com/register \
  -H "Authorization: Bearer $INITIAL_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "client_name": "My App",
        "redirect_uris": ["https://app.example.com/callback"],
        "grant_types": ["authorization_code"],
        "response_types": ["code"],
        "token_endpoint_auth_method": "client_secret_basic",
        "scope": "openid profile email"
      }'

The registration policy is fixed in code and cannot be loosened by configuration:

• Initial access token: always required. It is what binds the new client to an organization.
• Scopes: only openid, profile and email. offline_access is deliberately excluded, so a self-registered client gets no refresh tokens and has to come back through /authorize with a live session. Any nauthera.* scope is refused outright.
• Grant types: authorization_code and refresh_token.
• PKCE: always required_s256. No registration field changes it.
• Redirect URIs: at most 8.

Back-channel logout URIs (backchannel_logout_uri) can be registered only this way. A client's display name is checked for characters built to be misread, and suspicious names are recorded in the audit log.

#Getting an initial access token

An initial access token is an ordinary access token from the organization's /token endpoint that carries the nauthera.clients:register scope and an org claim. The org claim decides which organization the new client belongs to; nothing in the registration request can change that.

• A token issued to a user always carries org. Register a client through the gRPC AdminService with nauthera.clients:register among its scopes, and have someone sign in to it.
• A client_credentials token always carries org: the organization the server homed the client in when it was first stored. Register a confidential client with the client_credentials grant and nauthera.clients:register among its scopes, for example nauthera-cli create client registrar --grant-types client_credentials --scopes nauthera.clients:register. Every label under nauthera.dev/ is the server's own: the control plane refuses a client that sets one, so no writer can name another organization there.

The reserved {slug}-admin-* clients do not carry the scope.

A DPoP-bound initial access token must be sent with the DPoP scheme and a matching DPoP proof. A proof without a current nonce also answers 401: the body says invalid_token, the challenge says use_dpop_nonce, and a DPoP-Nonce header carries the nonce to retry with.

#Managing a registered client

• Identifiers. The server assigns the client_id (dcr_ followed by 128 random bits) and ignores one sent in the request. The secret is 256 random bits, returned once.
• Read and update need the registration access token. PUT replaces the whole configuration: a field left out is removed, not kept.
• Unknown clients look like bad tokens. An unknown client_id answers 401, never 404, so the endpoint cannot be used to discover client IDs.
• Clients registered through the AdminService cannot be changed over HTTP. They have no registration access token, so GET, PUT and DELETE on /register/{client_id} for one of them answer 401, the same as an unknown client_id.
• Deleting a client makes every later grant fail at once, but access tokens already issued stay valid until they expire.
• Unsupported metadata is dropped rather than stored, as RFC 7591 §2 requires: jwks, sector_identifier_uri, subject_type, request_object_signing_alg, userinfo_signed_response_alg, default_max_age, require_auth_time, default_acr_values and initiate_login_uri.

#Viewing clients

The admin API lists and reads an organization's clients, and the admin dashboard shows the same on its clients pages.

No secret material is ever returned: the detail says only whether the client holds a secret (has_secret). Registration contacts are returned only to a caller with the users.pii.read permission. A client of another organization answers 404, like one that does not exist. A display name built to be misread (direction overrides, control or invisible characters, padding, excessive length, markup) is flagged in display_name_markers.

The usage counts include only grants that act for a user: the authorization code, a refresh and the device code. A client_credentials token counts nobody. Each user counts once per window, and the window edges are exact to within an hour.

#Client settings

#Redirect URIs

Redirect URIs are matched exactly, with no wildcards and no prefix matching. Two relaxations that native apps need are not supported yet: any port on a loopback redirect and private-use URI schemes.

#Secrets

UpsertOIDCClient with rotate_secret mints a new secret for an existing client, replaces the stored digest and returns the plaintext once. The operator does this when the Secret holding an OIDCClient's secret is deleted. nauthera-cli cannot rotate a secret: delete the client and create it again.

#Scopes

Besides openid, profile, email and offline_access, the server reserves the nauthera. prefix for its own resource scopes. Every scope in it except nauthera.clients:register opens the admin API, and only an organization's own reserved admin console and machine clients may carry one. The control plane refuses them on any other client, dynamic registration refuses the whole prefix, and the admin API refuses a token from any other client whatever it carries. At startup the server removes admin scopes from any other client that still holds them and records each change in the audit log.

The machine client gets nauthera.users:read, nauthera.users:write and nauthera.audit:read, and in the main organization nauthera.orgs:read and nauthera.orgs:write too. The console gets the same plus the client, session, insights, threats, role, broker and domain scopes of the dashboard's other pages; a tenant organization's console also gets nauthera.orgs:read.

Admin scopes also need a matching RBAC role. See Admin API & Users.