# Eodly auth.md

This is the auth.md for Eodly: how an AI agent authenticates to the Eodly API. The
human-readable version with code examples lives at <https://eodly.io/developers>.

## Mechanism

Eodly uses long-lived, organization-scoped **API keys**, not an interactive
OAuth flow. A key is a bearer credential of the form `eodly_sk_...`. Eodly stores
only a SHA-256 hash of each key; the secret is shown once at creation.

> Note: Eodly does not operate an OAuth authorization server for its API, so there
> is intentionally no `/.well-known/oauth-authorization-server` or
> `/.well-known/oauth-protected-resource`. API keys are the supported credential.

## Obtaining a key (registration)

Keys are provisioned by a human account owner, not by dynamic client registration:

1. Sign in to Eodly as a founder or lead at <https://eodly.io/login>.
2. Open **Settings → API keys**.
3. Create a key, choose its scopes (request only what is needed), and copy the
   secret. It is shown once.

## Using a key

Send the key on every request as a bearer token:

```
Authorization: Bearer eodly_sk_YOUR_KEY
```

The `X-API-Key: eodly_sk_YOUR_KEY` header is also accepted. Verify a key with
`GET https://eodly.io/api/v1/me`, which returns the key's organization and scopes.

## Scopes

| Scope | Grants |
| --- | --- |
| `reports:read` | Read end-of-day reports for the key's organization. |
| `team:read` | Read the team roster for the key's organization. |

## Identifiers

- Base URL: `https://eodly.io/api/v1`
- API descriptor: <https://eodly.io/openapi.json>
- API catalog: <https://eodly.io/.well-known/api-catalog>
- Documentation: <https://eodly.io/developers>

## Errors

A missing or invalid key returns `401 unauthorized`. A valid key without the
required scope returns `403 insufficient_scope` with a `required_scope` field.
Revoke a key from Settings → API keys; revocation takes effect immediately.