> ## Documentation Index
> Fetch the complete documentation index at: https://developers.everhour.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth 2.1

> Authorize an app to call the Everhour API on a user's behalf using OAuth 2.1 with PKCE and Dynamic Client Registration — no app to create and no client secret.

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](https://datatracker.ietf.org/doc/html/rfc7591). 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.

<Note>
  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.
</Note>

## OAuth or an API key?

Everhour supports two ways to authenticate. Pick by who the caller is.

|                | [API key](/authentication)                 | OAuth 2.1                                                     |
| -------------- | ------------------------------------------ | ------------------------------------------------------------- |
| **Best for**   | Your own scripts and server-to-server jobs | Apps that act for other users (MCP clients, third-party apps) |
| **Credential** | One long-lived key per user                | Short-lived access token + rotating refresh token             |
| **Setup**      | Copy the key from your profile             | User signs in and approves in the browser                     |
| **Sent as**    | `X-Api-Key` header                         | `Authorization: Bearer` header                                |

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`](https://datatracker.ietf.org/doc/html/rfc8707) parameter at authorization. [MCP clients](/mcp-connect) 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.

<Steps>
  <Step title="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](https://datatracker.ietf.org/doc/html/rfc9728)) — names the authorization server.
    * `GET /.well-known/oauth-authorization-server` ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)) — lists the authorize, token, and registration endpoints.
  </Step>

  <Step title="Dynamic client registration">
    The client registers itself at `POST /oauth/register` ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) with a `client_name` and its `redirect_uris`, and receives a `client_id`. Clients are **public** — PKCE-protected, with no secret.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

```mermaid theme={null}
sequenceDiagram
    participant App as Your app
    participant API as api.everhour.com
    participant User as User's browser

    App->>API: Request without a token
    API-->>App: 401 + WWW-Authenticate (metadata URL)
    App->>API: GET discovery documents
    App->>API: POST /oauth/register (client_name, redirect_uris)
    API-->>App: client_id (public client)
    App->>User: Open /oauth/authorize (PKCE S256 challenge)
    User->>API: Sign in and click Allow
    API-->>App: Redirect with authorization code
    App->>API: POST /oauth/token (code + PKCE verifier)
    API-->>App: access_token (JWT, ~1h) + refresh_token
    App->>API: Request with Authorization: Bearer <token>
    API-->>App: 200 OK
```

## Next steps

<CardGroup cols={2}>
  <Card title="OAuth 2.1 reference" icon="book" href="/oauth-reference">
    Every endpoint, parameter, token lifetime, and security rule.
  </Card>

  <Card title="Connect an MCP client" icon="plug" href="/mcp-connect">
    The most common OAuth client — connect Claude, ChatGPT, Cursor, and more.
  </Card>
</CardGroup>