# Auth — Agent Registration for Veitia Studios APIs

Veitia Studios exposes protected APIs endpoints for booking management and
contact sync. AI agents can authenticate using OAuth 2.0 / OpenID Connect.

## 1. Discover authentication metadata

Agents SHOULD start by fetching the OAuth Protected Resource Metadata and the
Authorization Server Metadata:

- Protected resource: `https://veitiastudios.com/.well-known/oauth-protected-resource`
- Authorization server: `https://veitiastudios.com/.well-known/oauth-authorization-server`
- OpenID Connect: `https://veitiastudios.com/.well-known/openid-configuration`
- Signing keys (JWKS): `https://veitiastudios.com/.well-known/jwks.json`

## 2. Register your agent

Dynamic client registration is supported at:

```
POST https://veitiastudios.com/oauth/register
Content-Type: application/json
```

Request body:

```json
{
  "client_name": "My AI Agent",
  "redirect_uris": ["https://my-agent.example.com/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "client_secret_basic",
  "scope": "openid read:bookings write:bookings read:contacts write:contacts"
}
```

The response returns a `client_id`, `client_secret`, and registered
`redirect_uris`.

## 3. Obtain an access token

### Authorization Code flow

1. Redirect the user to the authorization endpoint with `response_type=code`,
   `client_id`, `redirect_uri`, `scope`, and a PKCE `code_challenge`.
2. Exchange the returned code at the token endpoint:

```
POST https://veitiastudios.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
code={code}
redirect_uri={redirect_uri}
client_id={client_id}
client_secret={client_secret}
code_verifier={code_verifier}
```

### Client Credentials flow (server-to-server)

```
POST https://veitiastudios.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
client_id={client_id}
client_secret={client_secret}
scope=read:bookings write:bookings
```

## 4. Call protected APIs

Send the access token as a Bearer token in the `Authorization` header:

```
GET https://veitiastudios.com/api/bookings
Authorization: Bearer {access_token}
```

## 5. Supported scopes

| Scope | Description |
|-------|-------------|
| `openid` | OpenID Connect authentication |
| `profile` | Read profile claims |
| `email` | Read email claim |
| `read:bookings` | Read booking slots and appointments |
| `write:bookings` | Create and modify appointments |
| `read:contacts` | Read contact records |
| `write:contacts` | Create and update contacts |

## 6. Refresh, revoke, and introspect tokens

- Refresh: `POST https://veitiastudios.com/oauth/token` with `grant_type=refresh_token`
- Revoke: `POST https://veitiastudios.com/oauth/revoke`
- Introspect: `POST https://veitiastudios.com/oauth/introspect`

## 7. Supported identity & credential types

- **Identity types:** `software`, `service_account`
- **Credential types:** `client_secret`, `private_key_jwt`
- **Signing algorithms:** `RS256`
- **PKCE methods:** `S256`, `plain`

## 8. Need help

See the full API documentation at `https://veitiastudios.com/docs/api` or the
API catalog at `https://veitiastudios.com/.well-known/api-catalog`.