Open-source OAuth 2.0 and OpenID Connect

Authentication,measured.

Authometry is the authorization server between your app and its users. Each request leaves a trace of every check it ran.

Inan authorization request
Checkedclient, identity, policy, consent
Outa token and its trace

Interactive example · demo data

Authorization flow: itsagram-web sends an authorization request to Authometry, which authenticates maya@bellaire.media, matches the workspace-member policy, confirms consent for openid, profile, media:read, and issues an RS256 access token 118.9 milliseconds after the request began. Select any step to see its recorded data.

Decision: Waiting
Elapsed: 0.0 ms
Trace: recording

Click, or tab to, any step to inspect what Authometry recorded.

Decision: Waiting
Elapsed: 0.0 ms

Tap a step to inspect its trace.

Tracerecording

Chapter 01See the decision

Every decision leaves a trace.

When a sign-in misbehaves, you shouldn’t have to guess. Authometry records every authorization and token request as it runs — each check, what it saw, how long it took, and the decision it reached.

Ordered: Every check is recorded in the order it ran, with its offset and duration.
Explained: A denial carries what was observed, what was expected, and how to fix it.
Redacted: Codes, tokens, secrets, cookies, and assertions are replaced before anything is stored.

Interactive example · demo data

QWhy was Maya Okafor let into Itsagram Web?

AEvery check passed — the session was valid and stored consent covered openid, profile, media:read.

/Bellaire Media/Production

Traces / req_Q2x7mL9kTa

Authorization code issued

Authorized

req_Q2x7mL9kTa

Export JSON

Application: Itsagram Web
User: maya@bellaire.media
Grant: Authorization Code + PKCE
Duration: 74.6 ms

The user completed authentication.
Outputs
User
Maya Okafor
Session
existing
user.groups
bellaire-media, editors
Allowed
The user session is valid.

Trace view recreated with demo data. Step names, fields, and decisions match what the authorization endpoint records.

Chapter 02Understand the denial

Debug a denial in one read.

A login succeeds.
A token fails.
A scope disappears.
A request is denied.

The client only gets a terse error code. The trace shows which check failed, what it expected, and what to change.

Interactive example · demo data

QWhy did the app get invalid_scope?

Amedia:write isn’t assigned to Itsagram Web.

HTTP/1.1 302 Found

Location: https://itsagram.com/auth/callback?error=invalid_scope&state=…

invalid_scope

Trace req_Hd4sZ0rWb2

Request
GET /oauth/authorize
scopeopenid profile media:write
Application
Client verified itsagram-web
Redirect URI matched exact
Scopes
Scope denied media:write
The client requested scopes it is not assigned.
Not run
User authenticatedConsent evaluatedAuthorization code issued
Decision
A requested scope is not assigned
media:write is not assigned to Itsagram Web.
Observedmedia:write
Expectedopenid profile media:read
How to fix it
Assign the scope to the application or remove it from the authorization request.
Manage application scopes

policy.decisions

Compare two decisions. See what changed.

Same person, same application, same scopes, ninety minutes apart. Authometry keeps both requests, so the one attribute that changed is visible — along with the policy condition it failed.

Interactive example · demo data

QSame person, same app — why was the second request denied?

Abellaire-media was removed from user.groups, so workspace-member no longer matched.

client_iditsagram-webitsagram-web

scopeopenid profile media:readopenid profile media:read

usermaya@bellaire.mediamaya@bellaire.media

environmentproductionproduction

user.groups (differs)bellaire-media, editors~~bellaire-media~~ editors

policy workspace-member conditions matched conditions not matched

user.groups_updated15:47:12An administrator removed Maya Okafor from bellaire-media.

policies/workspace-member.yaml

match:
  all:
    - field: user.groups
      operator: contains
      value: bellaire-media
decision:
  allow: true
otherwise:
  deny:
    code: access_denied
    message: A Bellaire Media workspace account is required.

Policy: Workspace memberreq_V8nP3wQe1c

Authorization policy denied the request

A Bellaire Media workspace account is required.

How to fix it

Review the user’s attributes or update the policy conditions.

Open policy

The client receives error=access_denied with the policy’s message — and you keep the reason.

Chapter 03Integrate it

Integrate with the library you already use.

Keep your OpenID Connect library and point it at your issuer. Every request it makes shows up as a trace — there is no Authometry SDK to learn.

The quickstart, in brief:

1Provision the client from your repository

$ npx authometry@latest apps create \
  --name "Itsagram Web" --type web \
  --redirect-uri https://itsagram.com/auth/callback \
  --scope openid --scope profile --scope media:read \
  --output-env .env.local

Writes AUTHOMETRY_ISSUER, AUTHOMETRY_CLIENT_ID, and a one-time AUTHOMETRY_CLIENT_SECRET to .env.local.

2Connect the library you already use

Follow the setup guide

Alternative: hand the same steps to a coding agent

Add Authometry OAuth to my app: https://authometry.jiayangchen.com/SKILL.md

auth.tsAuth.js

1import NextAuth from "next-auth";
2
3export const { handlers, auth, signIn, signOut } = NextAuth({
4  providers: [
5    {
6      id: "authometry",
7      name: "Authometry",
8      type: "oidc",
9      issuer: process.env.AUTHOMETRY_ISSUER,
10      clientId: process.env.AUTHOMETRY_CLIENT_ID,
11      clientSecret: process.env.AUTHOMETRY_CLIENT_SECRET,
12      authorization: { params: { scope: "openid profile media:read" } },
13      checks: ["pkce", "state", "nonce"],
14    },
15  ],
16});

Issuer, client ID, and secret come from the provisioning step. Library APIs shown as documented by each project.

Works with any compliant OAuth 2.0 or OIDC library.

Conformance-oriented tests ship with the code. Authometry is not OpenID Certified; certification is a separate submission to the OpenID Foundation.

Authorization Code + PKCES256 only
OpenID ConnectDiscovery, JWKS, ID token, UserInfo
Refresh tokensRotated on every use
Client CredentialsMachine-to-machine
Device AuthorizationTVs and CLIs
Token Exchange + DPoPBounded agent delegation

See the full standards matrix

platform.reference

Want the detail behind the trace?

Trace your first request.

See every authorization decision
Debug denials from the trace
Keep your OIDC library

Get started with Authometry Read the source(opens in a new tab)

match: all: - field: user.groups operator: contains value: bellaire-media decision: allow: true otherwise: deny: code: access_denied message: A Bellaire Media workspace account is required.

Integrate with the library you already use.

Keep your OpenID Connect library and point it at your issuer. Every request it makes shows up as a trace — there is no Authometry SDK to learn.

The quickstart, in brief:

1Provision the client from your repository

$ npx authometry@latest apps create \
  --name "Itsagram Web" --type web \
  --redirect-uri https://itsagram.com/auth/callback \
  --scope openid --scope profile --scope media:read \
  --output-env .env.local

Writes AUTHOMETRY_ISSUER, AUTHOMETRY_CLIENT_ID, and a one-time AUTHOMETRY_CLIENT_SECRET to .env.local.

2Connect the library you already use

Follow the setup guide

Alternative: hand the same steps to a coding agent

Add Authometry OAuth to my app: https://authometry.jiayangchen.com/SKILL.md

1import NextAuth from "next-auth"; 2 3export const { handlers, auth, signIn, signOut } = NextAuth({ 4 providers: [ 5 { 6 id: "authometry", 7 name: "Authometry", 8 type: "oidc", 9 issuer: process.env.AUTHOMETRY_ISSUER, 10 clientId: process.env.AUTHOMETRY_CLIENT_ID, 11 clientSecret: process.env.AUTHOMETRY_CLIENT_SECRET, 12 authorization: { params: { scope: "openid profile media:read" } }, 13 checks: ["pkce", "state", "nonce"], 14 }, 15 ], 16});