> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuro-tech.io/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth 2 authorization server

> Register clients, authorize scopes, issue JWTs, use device flow, and introspect tokens

<Warning>
  OAuth settings differ by Neuron version and operator configuration. Read the server metadata and confirm grants, registration, scopes, and token behavior before production use.
</Warning>

Current Neuron builds can act as an OAuth 2 authorization server.

## Endpoints

| Purpose                     | Path                                      | Standard      |
| --------------------------- | ----------------------------------------- | ------------- |
| Authorization               | `/oauth/authorize`                        | RFC 6749      |
| Token                       | `/oauth/token`                            | RFC 6749      |
| Dynamic registration        | `/oauth/register`                         | RFC 7591/7592 |
| Registration management     | `/oauth/registration`                     | RFC 7592      |
| Device authorization        | `/oauth/device`                           | RFC 8628      |
| Introspection               | `/oauth/introspect`                       | RFC 7662      |
| Authorization metadata      | `/.well-known/oauth-authorization-server` | RFC 8414      |
| Protected-resource metadata | `/.well-known/oauth-protected-resource`   | RFC 9728      |

PKCE and refresh tokens are supported. Use server metadata to discover the grants, signing algorithms, and client-authentication methods enabled by the running build.

## Choose a flow

* **Authorization Code + PKCE:** browser/mobile/desktop clients acting for a user.
* **Device authorization:** terminal, appliance, or agent without a usable browser.
* **Confidential client:** server-side application able to protect a secret.
* **mTLS or Neuron authentication exchange:** deployment-specific trusted client flows.

Do not use the implicit grant for new applications.

## Scopes to privileges

Neuron authorization is role-based. OAuth scopes map to privileges prefixed with `OAUTH.Scope.`, with colons changed to periods. An authenticated client receives a token only for scopes its backing account can authorize.

## Dynamic registration

The operator enables dynamic registration by creating an API key named `OAUTH`. Registrations are limited per remote endpoint. A registration creates a corresponding XMPP account with no useful privileges and normal XMPP communication disabled by default.

## Branding login pages

OAuth login UI is produced from Markdown and embedded into `MasterOAuth.md` in the web root. Package and version customizations; preserve CSRF, redirect-URI, consent, and error placeholders when changing the layout.

## Security checklist

* exact-match redirect URIs;
* PKCE for public clients;
* short-lived access tokens and protected refresh tokens;
* least-privilege scope grants;
* WAF restrictions for `/oauth/` where appropriate;
* never log codes, tokens, secrets, or verifier values;
* revoke/disable abandoned clients.