# Machine Authentication & Agent Authorization Guide — Oh my AI

> Specifications and machine authorization guide for AI agents interacting with Oh my AI production interfaces.

This document adheres to the [auth.md specification](https://github.com/workos/auth.md) and outlines how autonomous agents, integrations, and developers authenticate against Oh my AI services.

---

## 1. Discover

Agents can discover machine interfaces, API schemas, and authorization endpoints through standard discovery documents:

- **Protected Resource Metadata**: [/.well-known/oauth-protected-resource](https://ohmyai.nl/.well-known/oauth-protected-resource)
- **Model Context Protocol (MCP)**: [/.well-known/mcp](https://ohmyai.nl/.well-known/mcp)
- **OpenAPI 3.1 Specification**: [/openapi.json](https://ohmyai.nl/openapi.json)
- **Agentic Resource Discovery (ARD)**: [/.well-known/ard.json](https://ohmyai.nl/.well-known/ard.json)

When calling protected endpoints without credentials, the API responds with:
```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://ohmyai.nl/.well-known/oauth-protected-resource"
```

---

## 2. Pick a Method

Oh my AI supports three modes of agent interaction depending on trust level and execution environment:

1. **Anonymous / Open Machine Intake (`anonymous`)**:
   - Best for first-time discovery, scoping, and intake inquiries.
   - Requires no pre-shared keys. Protected by invisible anti-spam challenges (Botpoison) and edge rate-limiting.
   - Supported endpoints: `POST /api/intake`, `POST /api/mcp` (public tool execution).

2. **Service Account Authentication (`service_auth`)**:
   - Used by enterprise clients and deployed system agents.
   - Authentication via HTTP Bearer token in the `Authorization` header:
     ```http
     Authorization: Bearer <service_token>
     ```

3. **Identity Assertion (`identity_assertion`)**:
   - Agents representing a verified external principal provide a signed JWT or ID-JAG token (`urn:ietf:params:oauth:token-type:id-jag`).

---

## 3. Register

Autonomous agents requiring persistent integration or enterprise API access register programmatically via the intake endpoint or through enterprise onboarding:

- **Endpoint**: `POST https://ohmyai.nl/api/intake`
- **Payload**:
  ```json
  {
    "type": "agent",
    "name": "Integration Agent",
    "company": "Client Organisation",
    "email": "agent-operator@example.com",
    "process": "Automated workflow integration"
  }
  ```

---

## 4. Claim

Upon client engagement setup, Oh my AI issues client credentials and binds agent identities to designated workspace permissions.

- **Identity Endpoint**: `https://ohmyai.nl/api/auth/identity`
- **Supported Identity Types**: `service_auth`, `anonymous`, `identity_assertion`

---

## 5. Exchange

Agents exchange an assertion or API secret for short-lived session tokens via standard OAuth 2.0 token endpoint:

```http
POST /api/auth/token HTTP/1.1
Host: ohmyai.nl
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>
```

Response:
```json
{
  "access_token": "oma_live_token_sample",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "intake:write services:read mcp:execute"
}
```

---

## 6. Use the access_token

Include the access token in all API and MCP requests:

```http
POST /api/mcp HTTP/1.1
Host: ohmyai.nl
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_services",
    "arguments": {}
  }
}
```

---

## 7. Errors

Machine authentication failures return structured RFC 9457 error responses:

```json
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid bearer token",
    "hint": "Provide a valid token in the Authorization header or use open public endpoints"
  }
}
```

Common status codes:
- `401 Unauthorized`: Missing or invalid credentials. Returns `WWW-Authenticate` challenge.
- `403 Forbidden`: Insufficient scopes for the requested operation.
- `429 Too Many Requests`: Rate limit exceeded. Respect `Retry-After` header.

---

## 8. Revocation

Credentials can be revoked immediately by contacting engineering at `info@ohmyai.nl` or calling `POST /api/auth/revoke` with the token.