# Auth.md — Agent Authentication

Imejis supports AI-agent access via OAuth 2.0 (authorization code + PKCE).

## Authorization server
- Issuer: `https://api.console.buildbase.app/org/69de35486f55ea877a8b95fc`
- Metadata (RFC 8414): https://api.console.buildbase.app/.well-known/oauth-authorization-server/org/69de35486f55ea877a8b95fc

Fetch the metadata document above for the `authorization_endpoint`, `token_endpoint`, supported grant types / PKCE methods, and — when the app allows it — the dynamic client `registration_endpoint` (RFC 7591).

## Protected resources (RFC 9728)
See `/.well-known/oauth-protected-resource`, which lists the resource, its supported scopes, and the authorization server(s) that can issue tokens for it.

## How an agent authenticates
1. Discover this document and `/.well-known/oauth-protected-resource`.
2. Fetch the authorization-server metadata for the endpoints.
3. Register a client (dynamic registration) or use a pre-issued client_id.
4. Run the authorization-code flow with PKCE (S256), requesting the scopes and target `resource`.
5. Exchange the code for an access token and call the API with `Authorization: Bearer <token>`.

Documentation: https://www.imejis.io/apis

## Register and authenticate (self-contained flow)

Everything an agent needs, end to end. No pre-issued credentials required —
clients are registered dynamically (RFC 7591). Machine-readable registration
metadata lives in the `agent_auth` block of
https://www.imejis.io/.well-known/oauth-authorization-server — identity type
`anonymous`: register via `register_uri`, then bind a user at `claim_uri`
(the authorization endpoint) with the PKCE flow below; revoke tokens at
`revocation_uri`.

### 1. Register a client

```bash
curl -X POST 'https://api.console.buildbase.app/api/v1/auth/oauth2/register?org=69de35486f55ea877a8b95fc' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_name": "my-agent",
    "redirect_uris": ["http://localhost:8976/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "token_endpoint_auth_method": "none"
  }'
```

The response contains your `client_id` (and `client_secret` for confidential
clients).

### 2. Authorize (PKCE S256)

Generate a `code_verifier`, derive `code_challenge = BASE64URL(SHA256(verifier))`,
and send the user to:

```
https://api.console.buildbase.app/api/v1/auth/oauth2/authorize?org=69de35486f55ea877a8b95fc&client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&response_type=code&scope=read%20write&resource=https%3A%2F%2Fapi.imejis.io&code_challenge=<CODE_CHALLENGE>&code_challenge_method=S256&state=<STATE>
```

After login + consent the user is redirected to `redirect_uri` with `?code=...`.

### 3. Exchange the code for a token

```bash
curl -X POST 'https://api.console.buildbase.app/api/v1/auth/oauth2/token?org=69de35486f55ea877a8b95fc' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code&code=<CODE>&redirect_uri=<REDIRECT_URI>&client_id=<CLIENT_ID>&code_verifier=<CODE_VERIFIER>&resource=https%3A%2F%2Fapi.imejis.io'
```

### 4. Call the API

```bash
curl 'https://api.imejis.io/designs/v2' -H 'Authorization: Bearer <ACCESS_TOKEN>'
```

Access tokens are short-lived (~1 hour); use the `refresh_token` grant at the
same token endpoint to renew.

## MCP server

Imejis also exposes an MCP server (Streamable HTTP):

- Endpoint: `https://api.imejis.io/api/mcp`
- Server card: https://www.imejis.io/.well-known/mcp/server-card.json
- Protected-resource metadata (RFC 9728): https://api.imejis.io/.well-known/oauth-protected-resource/api/mcp

Authenticate it with the same OAuth flow above — connect to the endpoint, follow
the `WWW-Authenticate` challenge on the 401, and present the resulting access
token as `Authorization: Bearer <token>`.