---
name: oneid
description: Integrate applications, APIs and products with OneiD (an OpenID Connect and OAuth 2.0 provider). Use when adding "Sign in with OneiD", protecting an API with OneiD access tokens, calling an API with client credentials, or building a OneiD connector or plugin.
---

# OneiD integration skill

Follow these rules when you write code that talks to OneiD. When a detail is not here, read the page linked below; do not guess. The full documentation as one file: https://oltinid.com/llms-full.txt.

## Before writing code, get from the human

1. The OneiD address (issuer), for example `https://id.example.com`. Discovery: `<address>/.well-known/openid-configuration`.
2. The client ID, and whether the client is public (browser, mobile, desktop: no secret) or confidential (server: has a secret). Never put a secret into browser or mobile code.
3. The exact redirect URI and post-logout redirect URI registered on the client (exact string match, no wildcards).
4. The scopes the client may request (`openid profile email`, `roles`, `offline_access`, API scopes such as `orders.read`).
5. For a browser application: confirmation that its origin is in the client's allowed CORS origins.

Clients are registered by an administrator; there is no dynamic client registration.

## Key facts for agents

- OneiD is an OAuth 2.0 authorization server and OpenID Connect provider. Configure libraries from discovery: `https://YOUR_ONEID/.well-known/openid-configuration`.
- The issuer ends with a slash: `https://YOUR_ONEID/`. Compare `iss` with the discovery value exactly.
- Use the authorization code flow with PKCE (`S256` only) for every application with a user; `client_credentials` for services. Implicit, hybrid, password (ROPC) and device flows are not supported.
- Client authentication: `client_secret_basic` (preferred) or `client_secret_post`. `private_key_jwt` and mTLS cannot be used.
- Access tokens are RS256 JWTs with `iss`, `sub`, `exp`, `scope`, `client_id` and no `aud`. APIs check signature (JWKS), issuer, expiry and the required scope; they must not require an audience.
- Refresh tokens (scope `offline_access`) rotate on every use; store the new one. Reuse after a short grace period revokes the chain.
- Sign-out: RP-initiated logout at `/connect/logout` with `id_token_hint` and a registered `post_logout_redirect_uri`. No front-channel or back-channel logout.
- Clients are registered by an administrator (no dynamic registration). Browser clients need their origin in the client's allowed CORS origins.
- Key users by `iss` + `sub`, never by email. Roles are in the `role` claim (scope `roles`).
- Not supported: SAML, SCIM, PAR, JAR, DPoP, token exchange, CIBA, `login_hint`, `ui_locales`, enforcement of `acr_values` (check `acr`/`amr` in the ID token instead).

## Steps

- **Sign-in (web, SPA, native):** https://oltinid.com/docs/guides/authorization-code-pkce.md: use a maintained OpenID Connect library and configure it from discovery. Quickstarts: https://oltinid.com/docs/quickstarts.md
- **ID token validation:** signature (JWKS, RS256), `iss` equals the discovery issuer (with the trailing slash), `aud` contains the client ID, `exp`, `nonce`. https://oltinid.com/docs/reference/tokens.md
- **User mapping:** key accounts by `iss` + `sub`; read `name`, `email`, `email_verified`, `role`. https://oltinid.com/docs/reference/claims.md
- **API protection:** https://oltinid.com/docs/guides/protect-an-api.md: check signature, issuer, expiry and the required scope; no audience check.
- **Machine to machine:** https://oltinid.com/docs/guides/client-credentials.md: cache the token until shortly before `expires_in`.
- **Refresh tokens:** https://oltinid.com/docs/guides/refresh-tokens.md: store the new refresh token after every refresh; serialise refreshes.
- **Sign-out:** https://oltinid.com/docs/guides/logout.md
- **Errors and rate limits:** https://oltinid.com/docs/reference/errors.md and https://oltinid.com/docs/reference/rate-limits.md (HTTP 429 with `Retry-After`).
- **Building a connector or plugin:** follow https://oltinid.com/docs/ai/connector-specification.md and tick its checklist.

## Never

- Never use the implicit flow, the password grant, `plain` PKCE, or `private_key_jwt`.
- Never log, persist in URLs, or send tokens to third parties.
- Never key users by email address.
- Never require an `aud` claim in OneiD access tokens.
- Never hard-code endpoint paths when the library can read discovery.