# OpenID Connect — Routebase

> The identity layer on top of OAuth 2.0, why an ID token is not an access token, what discovery buys you, and when plain OAuth is the right answer instead.

Canonical page: https://routebase.dev/guides/api-authentication/openid-connect/
Chapter 5 of 11 · API Authentication · Last reviewed 2026-09-12 · The Routebase Team

OAuth 2.0 answers what a client may do. It deliberately says nothing about who the user is, and for years people built their own answer on top of it, usually by calling some user-information endpoint and hoping the semantics matched.

OpenID Connect standardises that. It is an identity layer on top of OAuth 2.0, specified as OpenID Connect Core 1.0, and it adds three things to a flow you already know.

## What OpenID Connect adds

**An ID token.** A JWT containing claims about the authentication event, addressed to the client that asked for it.

**A standard `openid` scope.** Requesting it is what turns an OAuth flow into an OpenID Connect flow, and further scopes such as `profile` and `email` ask for specific claim sets.

**A discovery document and a key set.** Published at well-known URLs, so a client configures itself and picks up rotated signing keys without a deployment.

Everything else is OAuth. The authorization code flow with PKCE is the same flow, the same redirect, the same code exchange. The token response carries an `id_token` alongside the access token.

## The distinction that trips people up

An ID token and an access token are not interchangeable, and treating them as if they were is the most common OpenID Connect mistake.

| | ID token | Access token |
|---|---|---|
| Answers | Who authenticated, and how | What the bearer may do |
| Audience | The client that requested it | The API it is meant for |
| Format | Always a JWT with defined claims | Whatever the authorization server chooses |
| Sent to an API | No | Yes |
| Validated by | The client | The resource server |

The failure mode is sending the ID token to your API because it happens to be a JWT and it happens to contain the user's identifier. The API then validates a token whose audience is somebody else, which means the audience check either fails or was never implemented. If it was never implemented, the API will accept an ID token issued for any client at that provider.

## The claims to check

An ID token is a JWT, so everything in [bearer tokens and JWT](/guides/api-authentication/bearer-tokens-and-jwt/) applies. OpenID Connect adds a few requirements of its own.

| Claim | What to check |
|---|---|
| `iss` | It matches the issuer you configured, exactly |
| `aud` | It contains your client identifier |
| `exp` | It has not passed |
| `nonce` | It matches the value you sent in the authorization request |
| `azp` | Where present, it is your client identifier |
| `at_hash` | Where present, it matches the access token you received |

The `nonce` is the one people skip. It binds the ID token to the specific authentication request the client started, and it is what stops a token replayed from another session being accepted.

One more claim deserves a warning. The `email` claim is not proof of an email address unless `email_verified` is true. An application that links accounts on the email claim alone will link them to whatever address somebody typed at the provider.

## Discovery, and why it matters more than it looks

The discovery document lives at a well-known path under the issuer and publishes the endpoints, the supported scopes and response types, and the location of the signing key set.

The convenience of not typing endpoint URLs is minor. The part that matters is the key set, because a client that reads it at runtime picks up a rotated signing key on its own. Without that, key rotation is a coordinated deployment across every client, which means it does not happen.

Two practical notes. Cache the key set with a sensible lifetime instead of fetching it per request, and refetch when you see a key identifier you do not recognise. And read the discovery document over TLS from the issuer you configured, because a client that discovers its issuer from user input can be pointed at somebody else's.

## When plain OAuth is the better answer

OpenID Connect is not a strict upgrade. It asks for identity, which means consent screens that mention personal data, and it hands you personal data you then have to store and protect.

Use it when the identity is part of what you are building, so signing a user in, displaying their name, or linking a local account to an external one.

Skip it when you only need permission to call an API on somebody's behalf. A calendar integration that reads and writes events needs delegated access, and it does not need to know the user's name and email unless it displays them.

## In Routebase

OpenID Connect appears in two places, and they serve different purposes.

_Screenshot: All four OpenAPI scheme types are available when you create a component, including OpenID Connect._

**In the specification.** A security scheme component of type `openIdConnect` documents that an endpoint accepts OpenID Connect, and it carries the discovery URL so consumers and agents know where to configure themselves from. Schemes are created once per specification and attached to endpoints, and one action assigns a scheme across all endpoints, a folder, a tag or a hand-picked selection. That last part matters more than it sounds, because an endpoint nobody got around to securing looks exactly like one that is deliberately public.

**In testing.** An OpenID Connect deployment issues ordinary OAuth access tokens, so testing against it uses the OAuth 2.0 authentication type with the authorization code or client credentials grant. The Bearer type covers the case where a pipeline supplies the token. The ID token is a client-side concern and not something an API test sends.

See [Components](https://docs.routebase.dev/components/) for security schemes in the designer and [Project Auth](https://docs.routebase.dev/project-auth/) for the test-side configuration. The chapter on [designing authentication into your specification](/guides/api-authentication/openapi-security-schemes/) covers the documentation side in full.

## Frequently asked questions

### What is OpenID Connect?

OpenID Connect is an identity layer built on top of OAuth 2.0, specified as OpenID Connect Core 1.0. Where OAuth answers what a client is permitted to do, OpenID Connect answers who the user is, by adding an ID token containing verified claims about them. It reuses the OAuth authorization code flow, so a service that already speaks OAuth adds identity instead of replacing anything.

### What is the difference between an ID token and an access token?

An ID token is a statement about who authenticated, addressed to the client that requested it, and it is always a JWT with a defined set of claims. An access token is a credential for calling an API, and its format is not the client's business. Sending an ID token to an API as if it were an access token is a common mistake, because the API is not its intended audience and validating it there proves the wrong thing.

### What is the OpenID Connect discovery document?

It is a JSON document at a well-known URL that publishes everything a client needs to configure itself. That covers the authorization and token endpoints, the supported scopes and response types, and the location of the signing keys. It matters most for key rotation, since a client that reads the key set from discovery picks up a new signing key without a deployment.

### When should you use OpenID Connect instead of plain OAuth 2.0?

Use OpenID Connect when your application needs to know who the user is, which covers signing somebody in, showing their name, or linking a local account to an external identity. Use plain OAuth 2.0 when you only need permission to call an API on their behalf and the user's identity is not part of what you are building. Asking for identity you do not need adds consent friction and personal data you then have to handle.

---

[Routebase](https://routebase.dev/) — [Sign up](https://app.routebase.dev/): Every account starts with a 14-day Pro trial — no credit card required.