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

# Authentication

> Use an API key or an OAuth 2.0 access token.

<Tabs>
  <Tab title="API key">
    Use an API key for scripts and integrations that access your own organization.

    Create a key in **Settings → API** in the Entendre dashboard. Include it in the `X-API-Key` header:

    ```http theme={null}
    X-API-Key: <api_key>
    ```

    Your organization is inferred from its API key. You do not need to include an organization ID.
  </Tab>

  <Tab title="OAuth 2.0">
    Use OAuth when your app accesses Entendre on behalf of another user. The user chooses an organization and grants access.

    Send the access token in the `Authorization` header:

    ```http theme={null}
    Authorization: Bearer <access_token>
    ```

    | Scope       | Access                 |
    | ----------- | ---------------------- |
    | `apis.read` | Read access.           |
    | `apis.all`  | Read and write access. |

    <Accordion title="Authorization, refresh and revocation">
      Use a registered OAuth client and the authorization code flow with PKCE S256.

      1. Redirect the user to `https://api.entendre.finance/oauth/authorize` with `response_type=code`, `client_id`, the registered `redirect_uri`, `scope`, a random `state`, `code_challenge` and `code_challenge_method=S256`.
      2. Verify `state` when the user returns to your callback.
      3. Exchange the code at `POST https://api.entendre.finance/oauth/token` with `grant_type=authorization_code`, `client_id`, `code`, `redirect_uri` and the original PKCE `code_verifier`.
      4. Refresh at the same URL with `grant_type=refresh_token`, `client_id` and `refresh_token`.
      5. Disconnect at `POST https://api.entendre.finance/oauth/revoke` with form fields `token` (a refresh token) and `client_id`. Both are required, and the token must belong to that client. This revokes the whole authorization, including its access tokens.

      Access tokens expire after one day. Refresh them before expiry. Refresh tokens expire after 90 days of inactivity and rotate on use; store the replacement returned by each refresh.

      Reconnecting the same user and organization to the same client connection replaces the previous authorization. Store the new tokens; refresh tokens from a replaced authorization stop working.

      Revocation returns `200` with no body on success, including an unknown, expired or already-revoked token for that client. Invalid requests return `400`. If it returns `503` with a `Retry-After` header, wait that many seconds before you retry.
    </Accordion>
  </Tab>
</Tabs>

Keep keys and tokens out of browser code and version control. Send authenticated requests over HTTPS.