Skip to main content
OAuth 2.1 lets an app call the Everhour API on behalf of a user without holding that user’s API key. The user signs in and approves access in their browser, and your app receives a short-lived access token instead of a long-lived credential. Everhour implements OAuth 2.1 with the authorization code grant, PKCE, and Dynamic Client Registration. Your app registers itself and discovers every endpoint from the server’s metadata — there’s no application to create in a dashboard and no client secret to manage.
There’s nothing to set up in Everhour ahead of time — no app to create, no client ID or secret to copy, no redirect URL to pre-register. Your app registers itself the first time it connects, and the user approves access in the browser.

​
OAuth or an API key?

Everhour supports two ways to authenticate. Pick by who the caller is. Both methods act as the signed-in user and are bound by that user’s Everhour role — neither grants more than the person behind it can do.

​
What a token can access

An access token is a JSON Web Token (JWT) that is audience-bound to a resource:
  • By default a token is issued for the whole API (https://api.everhour.com) and works on every REST endpoint.
  • A client can narrow the token to a single resource by passing the resource parameter at authorization. MCP clients request https://api.everhour.com/mcp, so their token is accepted only on /mcp.
Everhour has no OAuth scopes. Access is governed entirely by the signed-in user’s role, the same as the API key. The consent screen lists what the app will be able to do so the user can make an informed decision, but there are no per-scope toggles.

​
How the flow works

Compatible clients run this end to end on their own — you configure your app with the server URL and it discovers the rest.
1

Discovery

An unauthenticated request to a protected resource returns 401 with a WWW-Authenticate header pointing to the protected-resource metadata. The client reads two documents:
  • GET /.well-known/oauth-protected-resource (RFC 9728) — names the authorization server.
  • GET /.well-known/oauth-authorization-server (RFC 8414) — lists the authorize, token, and registration endpoints.
2

Dynamic client registration

The client registers itself at POST /oauth/register (RFC 7591) with a client_name and its redirect_uris, and receives a client_id. Clients are public — PKCE-protected, with no secret.
3

Authorization code + PKCE

The client sends the user to /oauth/authorize with a PKCE S256 challenge. The user signs in, reviews the consent screen, and clicks Allow. Everhour redirects back to the client with a one-time code.
4

Token exchange

The client exchanges the code (with its PKCE verifier) at POST /oauth/token for an access token (a JWT, valid ~1 hour) and a rotating refresh token.
5

Authenticated calls

The client calls the API with Authorization: Bearer <access_token> and uses the refresh token to get a new access token when the old one expires.

​
Next steps

OAuth 2.1 reference

Every endpoint, parameter, token lifetime, and security rule.

Connect an MCP client

The most common OAuth client — connect Claude, ChatGPT, Cursor, and more.