# Authenticating with the OrchestKit API

> The OrchestKit documentation and search API are public and read-only. No authentication, API key, or account is required. Agents call the endpoints directly.

## Discover

An agent discovers how to use this API in three steps, none of which require a credential:

1. **RFC 9727 API catalog** — fetch `https://orchestkit.yonyon.ai/.well-known/api-catalog` (`application/linkset+json`). Its `linkset` `item` entries point to the OpenAPI spec, the `/ask` endpoint, and the MCP server.
2. **A2A agent card** — fetch `https://orchestkit.yonyon.ai/.well-known/agent-card.json` for the capabilities/skills and the transport endpoints.
3. **OpenAPI** — fetch `https://orchestkit.yonyon.ai/api/openapi` for the full request/response shapes.

RFC 9728 protected-resource metadata exists at `https://orchestkit.yonyon.ai/.well-known/oauth-protected-resource` and signals **anonymous-only access** in spec shape: `authorization_servers` and `bearer_methods_supported` are both empty arrays, because no authorization server exists and no bearer token is ever read. No `WWW-Authenticate` challenge is returned by any endpoint — there is never a `401` to challenge.

### For agents

Start at the RFC 9727 catalog: `GET https://orchestkit.yonyon.ai/.well-known/api-catalog`. The PRM at `/.well-known/oauth-protected-resource` confirms anonymous-only access; `/.well-known/oauth-authorization-server` 404s intentionally — there is no authorization server, and publishing RFC 8414 metadata for one that does not exist would be misleading. OAuth and agentic-registration flows are omitted because every resource here is public, free, and read-only: there is no tenant data to scope, no quota tied to identity, and no write surface to protect.

Sample discovery responses (live, abbreviated):

```json
// GET https://orchestkit.yonyon.ai/.well-known/oauth-protected-resource
{
  "resource": "https://orchestkit.yonyon.ai",
  "authorization_servers": [],
  "bearer_methods_supported": [],
  "resource_documentation": "https://orchestkit.yonyon.ai/auth.md"
}
```

```json
// GET https://orchestkit.yonyon.ai/.well-known/api-catalog  (application/linkset+json)
{ "linkset": [ { "anchor": "…/.well-known/api-catalog",
    "item": [ { "href": "…/api/openapi" }, { "href": "…/ask" }, { "href": "…/api/mcp" } ] } ] }
```

## Pick a method

There is one method: **anonymous access** — the sole supported identity type. Every endpoint is reachable without a bearer token, cookie, or signature.

**This API does not support agentic registration; the registration walkthrough is N/A by design.** There is no `register_uri`, `claim_uri`, or `revocation_uri`, and no `agent_auth` block — there is nothing to register for. A PRM fetch succeeds and confirms this (see Discover); a `401`-driven discovery handshake will never occur because no endpoint returns `401`.

## Use the credential

No credential is used. Send the request directly. Examples:

```http
GET https://orchestkit.yonyon.ai/api/search?query=install HTTP/1.1
Accept: application/json
```

```http
POST https://orchestkit.yonyon.ai/ask HTTP/1.1
Content-Type: application/json

{ "query": "How do I install OrchestKit?" }
```

The MCP server at `https://orchestkit.yonyon.ai/api/mcp` (Streamable HTTP) is likewise open — connect without credentials.

## Errors

Errors use the RFC 9457 Problem Details shape — a machine-readable `type`, `title`, `status`, and `detail` — served as `application/json`. The error codes you may encounter:

| HTTP status | `title` | When |
| --- | --- | --- |
| `400` | Missing query parameter / Invalid request body | Malformed request (e.g. empty `query`, non-JSON body). |
| `404` | API endpoint not found / Not found | Unknown path or a non-existent doc page. |
| `405` | Method Not Allowed | Wrong HTTP method (e.g. `GET` on `/api/mcp`). |
| `429` | Too Many Requests | Not enforced today (no per-key quota); if a CDN edge returns it, honor `Retry-After`. |
| `5xx` | — | Transient; retry with exponential backoff (1s, 2s, 4s). |

A `400` problem body looks like this — served as `application/json`:

```json
{
  "type": "https://orchestkit.yonyon.ai/docs/api/errors#missing-query-parameter",
  "title": "Missing query parameter",
  "status": 400,
  "detail": "The `query` parameter is required and must be a non-empty string."
}
```

Auth-specific codes are intentionally **not** used: you will never receive `401 Unauthorized` / `invalid_token` / `insufficient_scope` for a missing credential, because none is required.

None of the canonical auth.md error codes apply here, for the same reason: `invalid_request`, `invalid_client`, `invalid_grant`, `unauthorized_client`, `unsupported_grant_type`, `invalid_scope`, `invalid_token`, `insufficient_scope`, `interaction_required`, `login_required`, `consent_required`, and `registration_not_supported` are all OAuth-flow errors, and there is no OAuth flow. The only errors this API returns are the request-shape and availability errors in the table above.

## Revocation

Not applicable — there are no credentials to revoke.

## Webhooks

OrchestKit does not emit webhooks — the API is read-only, request/response only — so there is no webhook registration and no webhook signature scheme to verify. Mentions of "webhooks" in the documentation are skill/agent content for building webhooks in your own applications. See the [API policy](/api-policy.md) page.