# Agent Authentication for Beyin APIs

This document describes how AI agents and automated clients can authenticate
against Beyin's public APIs.

## Issuer

The OAuth 2.0 / OpenID Connect authorization server is operated by Supabase:

- **Issuer**: `https://zedwyuxzrokmyndsgnnl.supabase.co/auth/v1`
- **Authorization endpoint**: `https://zedwyuxzrokmyndsgnnl.supabase.co/auth/v1/authorize`
- **Token endpoint**: `https://zedwyuxzrokmyndsgnnl.supabase.co/auth/v1/token`
- **JWKS**: `https://zedwyuxzrokmyndsgnnl.supabase.co/auth/v1/.well-known/jwks.json`
- **UserInfo**: `https://zedwyuxzrokmyndsgnnl.supabase.co/auth/v1/user`

Full machine-readable metadata:

- [`/.well-known/openid-configuration`](/.well-known/openid-configuration)
- [`/.well-known/oauth-authorization-server`](/.well-known/oauth-authorization-server)
- [`/.well-known/oauth-protected-resource`](/.well-known/oauth-protected-resource)

## Protected resource

- **Resource identifier**: `https://beyin-api-pald5.ondigitalocean.app/api/v1`
- **API catalog**: [`/.well-known/api-catalog`](/.well-known/api-catalog)
- **Bearer method**: `Authorization: Bearer <jwt>` header
- **Scopes**: `openid`, `email`, `profile`

Some endpoints listed in the API catalog are public (no token required).
Endpoints that require authentication will respond with `401 Unauthorized` and
a `WWW-Authenticate: Bearer` header pointing back to this discovery metadata.

## Agent registration

Beyin currently uses Supabase's email/password identity model. To register an
agent identity:

1. Create a Supabase user via the public sign-up endpoint:

   ```http
   POST https://zedwyuxzrokmyndsgnnl.supabase.co/auth/v1/signup
   apikey: <SUPABASE_ANON_KEY>
   Content-Type: application/json

   {
     "email": "agent-name@your-domain.example",
     "password": "<strong-random-secret>",
     "data": { "identity_type": "agent", "agent_name": "your-agent" }
   }
   ```

2. The Supabase anon key for this project is the publishable `apikey` header
   value listed in `/.well-known/openid-configuration` consumers. It is safe to
   embed in agent code; it does **not** grant elevated access.

3. Confirm the email if email confirmation is enabled for the project, then
   exchange credentials for an access token (see below).

For higher-trust agent onboarding (service accounts, signed software statements,
client credentials), contact `hello@beyin.me`.

## Obtaining an access token

### Password grant (machine identity)

```http
POST https://zedwyuxzrokmyndsgnnl.supabase.co/auth/v1/token?grant_type=password
apikey: <SUPABASE_ANON_KEY>
Content-Type: application/json

{
  "email": "agent-name@your-domain.example",
  "password": "<strong-random-secret>"
}
```

Response contains `access_token` (JWT), `refresh_token`, and `expires_in`.

### Refresh grant

```http
POST https://zedwyuxzrokmyndsgnnl.supabase.co/auth/v1/token?grant_type=refresh_token
apikey: <SUPABASE_ANON_KEY>
Content-Type: application/json

{ "refresh_token": "<refresh_token>" }
```

### Authorization code + PKCE (interactive)

Use the standard OIDC authorization code flow with `code_challenge_method=S256`
against the authorization endpoint above. See the `code_challenge_methods_supported`
field in `/.well-known/openid-configuration`.

## Calling the API

```http
GET https://beyin-api-pald5.ondigitalocean.app/api/v1/public/services
Authorization: Bearer <access_token>
```

## Token revocation

Revoke a refresh token by calling Supabase's logout endpoint with the access
token in the `Authorization` header:

```http
POST https://zedwyuxzrokmyndsgnnl.supabase.co/auth/v1/logout
Authorization: Bearer <access_token>
apikey: <SUPABASE_ANON_KEY>
```

## Contact

Security issues or auth questions: `security@beyin.me`.