§08Lesson · Advanced
Federation Endpoints
The HTTP APIs that federation entities expose
12 min readLast reviewed 2026-06-05Advanced
OpenID Federation defines 1 well-known discovery URL (§9), 7 federation endpoints (§8), and 1 registration endpoint (§12.2). Not every entity implements all of them — leaf entities only need the well-known URL, while Trust Anchors and Intermediates may implement up to eight. The registration endpoint is exposed by OpenID Providers, not Trust Anchors.
Media Types
The federation endpoints return JWT-encoded responses with specific IANA-registered media types defined in §15. Servers MUST use the correct Content-Type header so clients can route the body to the right validator.
| Media Type | Used By | Spec |
|---|---|---|
| application/entity-statement+jwt | Entity Configurations & Subordinate Statements | §15.1 |
| application/trust-mark+jwt | Trust Marks | §15.2 |
| application/resolve-response+jwt | Resolve endpoint responses | §15.3 |
| application/trust-chain+json | Trust Chain header parameter | §15.4 |
| application/trust-mark-delegation+jwt | Trust Mark delegations | §15.5 |
| application/jwk-set+jwt | Historical Keys responses | §15.6 |
| application/trust-mark-status-response+jwt | Trust Mark Status responses | §15.7 |
| application/explicit-registration-response+jwt | Explicit Registration responses | §15.8 |
PrivacyPrivacy consideration
The Fetch endpoint and the Trust Mark Status endpoint can leak entity relationships via server access logs and DNS lookups: every query reveals "entity X is investigating entity Y." Operators handling sensitive populations should mitigate this by serving short-lived static Trust Chains (so resolvers don't need to call back), and by avoiding the
sub parameter on Trust Mark listing endpoints when possible.Real-World Analogy
Think of a government building with multiple service windows — each serves a specific purpose. The "Entity Configuration" window is at the front door (everyone has it). The "Fetch" and "List" windows are inside, only available to entities that manage subordinates.
Further reading
Normative spec
- §8Federation Endpoints
- §8.1Fetching a Subordinate Statement
- §8.2Subordinate Listing
- §8.3Resolve Entity
- §8.4Trust Mark Status
- §8.5Trust Marked Entities Listing
- §8.6Federation Trust Mark Endpoint
- §8.7Historical Keys
- §9Obtaining Federation Entity Configuration Information
- §12.2Explicit Registration
- §15Media Types
Normative RFCs