OAuth2 leaves the public contract

ChangelogAug 23, 2026Improved

The OAuth2 security scheme is gone from the published spec: from the global security block, from securitySchemes, and from every operation that declared it. Nothing changes at runtime — the authorization endpoints, the tokens already issued and the per-endpoint scope enforcement are all exactly as they were.

What replaces it in the document is more useful than what it removed: every operation now says which scope it needs, in prose you can read in this reference.

What else changed

Why it goes. There was no way for a third party to register a client, so the spec offered a flow on hundreds of operations that only we could actually use. Documenting a mechanism nobody can exercise is worse than not documenting it.
Where the scope lives now. Each operation's description carries a line like **Required scope:** invoices:write, and the full scope catalogue — which used to hang off the OAuth2 flow — is a table in the description of ApiKeyAuth.
Nothing to do. API key authentication (Authorization: Bearer beel_sk_…) is untouched. If you generate a client from the spec, the new one simply stops offering an OAuth2 flow you could not use.
It can come back. The day third-party application registration exists, OAuth2 returns to the contract with its catalogue and its flow.

Where to go next

Authentication