# Discovery

Two RFC-defined discovery documents are published at the API origin. Use them
to bootstrap OAuth clients without hard-coding endpoint URLs.

| Document | Path | Spec |
|---|---|---|
| Authorization server | `/.well-known/oauth-authorization-server` | RFC 8414 |
| Protected resource | `/.well-known/oauth-protected-resource` | RFC 9728 |

Both are unauthenticated `GET` endpoints and return raw JSON (no
`{ "data": …, "meta": … }` envelope).

## Authorization-server metadata

```bash
curl https://api.42min.us/.well-known/oauth-authorization-server
```

```json
{
  "issuer": "https://api.42min.us",
  "authorization_endpoint": "https://api.42min.us/v1/oauth/authorize",
  "token_endpoint": "https://api.42min.us/v1/oauth/token",
  "revocation_endpoint": "https://api.42min.us/v1/oauth/revoke",
  "introspection_endpoint": "https://api.42min.us/v1/oauth/introspect",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post",
    "none"
  ],
  "revocation_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post",
    "none"
  ],
  "introspection_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post"
  ],
  "scopes_supported": ["user:read", "event_types:read", "…"]
}
```

Notes:

- `response_types_supported` and `grant_types_supported` are intentionally
  short — only **authorization code** and **refresh token** grants are
  supported. Implicit, password, and client-credentials grants are not.
- `code_challenge_methods_supported` is **`["S256"]`** only. Plain PKCE
  challenges are rejected.
- `registration_endpoint` appears only when **Dynamic Client Registration** is
  enabled on the deployment. The hosted `api.42min.us` deployment does **not**
  expose it — register OAuth apps via
  [Admin Center → API](/360/api) instead.
- `scopes_supported` is the union of active and reserved scopes — see
  [Scopes](/help/api/scopes).

## Protected-resource metadata

```bash
curl https://api.42min.us/.well-known/oauth-protected-resource
```

```json
{
  "resource": "https://api.42min.us",
  "authorization_servers": ["https://api.42min.us"],
  "scopes_supported": ["user:read", "event_types:read", "…"],
  "bearer_methods_supported": ["header"]
}
```

`bearer_methods_supported: ["header"]` is the only accepted form — bearer
tokens travel in `Authorization: Bearer …`, never as query parameters or form
fields on the resource endpoints.

## Why use discovery

- **One-time client setup.** Read the document at boot, cache the endpoint
  URLs for the lifetime of the process. You won't need to update your code if
  any of the endpoint paths change.
- **Standard OAuth libraries.** Most libraries can pull the endpoints from
  the discovery document automatically.
- **Scope enumeration.** `scopes_supported` is the authoritative list — match
  it against your UI's checkboxes.