# AINative — Agent Authentication (auth.md)

> Last updated: 2026-09-25
> Spec: [WorkOS auth.md](https://github.com/workos/auth.md) — a machine-readable
> skill file that tells an autonomous agent how to authenticate to this service.

This file is the third step of AINative's OAuth agent-discovery chain. An
agent that hits a `401` on an AINative API should be able to walk the chain
end to end without a human in the loop:

1. **RFC 9728 protected-resource metadata** —
   `GET https://api.ainative.studio/.well-known/oauth-protected-resource`
   tells the agent which authorization server issues tokens for this API
   (`authorization_servers: ["https://api.ainative.studio"]`).
2. **RFC 8414 authorization-server metadata** —
   `GET https://api.ainative.studio/.well-known/oauth-authorization-server`
   publishes the real `issuer`, `token_endpoint`, and `grant_types_supported`
   for that authorization server.
3. **This file** — `https://ainative.studio/auth.md` — explains, in prose and
   in the structured `agent_auth` block below, exactly how to use that
   `token_endpoint` to get a working credential.

## How to authenticate as an agent

AINative's authorization server currently supports one authentication mode
for autonomous agents: **OAuth 2.1 client-credentials (`service_auth`)**.
This is confirmed live today — `grant_types_supported` on the real
`/.well-known/oauth-authorization-server` response is `["client_credentials"]`.

1. Obtain a `client_id` / `client_secret` pair. (Agent OAuth clients are
   created via the AINative Cloud Auth console today; there is no unauthenticated
   self-registration endpoint yet, so an agent acting fully autonomously should
   fall back to the **Instant DB** path below instead.)
2. Exchange those credentials for an access token:

   ```bash
   curl -X POST https://api.ainative.studio/api/v1/cloud/auth/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials" \
     -d "client_id=<your_client_id>" \
     -d "client_secret=<your_client_secret>" \
     -d "scope=zerodb.read zerodb.write"
   ```

   Returns a bearer `access_token`, `token_type`, `expires_in`, and the
   granted `scope`. Send it as `Authorization: Bearer <access_token>`.

3. Tokens can be introspected (`POST /api/v1/cloud/auth/token/introspect`,
   RFC 7662) or revoked (`POST /api/v1/cloud/auth/token/revoke`, RFC 7009)
   at the same authorization server.

### Zero-human alternative: Instant DB API keys

If your agent has no pre-provisioned OAuth client, it can self-provision an
API key with no signup and no human approval:

```bash
curl -X POST https://api.ainative.studio/api/v1/public/instant-db \
  -H "Content-Type: application/json" \
  -d '{"agree_terms": true}'
```

This returns a temporary `api_key` (`tmp_` prefix) usable immediately as an
`X-API-Key` header. See `https://ainative.studio/agent.md` for the full
zero-human provisioning, MCP, and SDK quick-start.

## agent_auth (machine-readable)

The block below follows the WorkOS auth.md spec's `agent_auth` profile
extension. Field values are taken directly from AINative's live discovery
metadata as of 2026-09-25:

```json
{
  "agent_auth": {
    "skill": "https://ainative.studio/auth.md",
    "identity_endpoint": "https://api.ainative.studio/api/v1/cloud/auth/token",
    "identity_types_supported": ["service_auth"]
  }
}
```

Field notes:

- **`skill`** — this file's own canonical URL, per the spec's cross-linking
  convention.
- **`identity_endpoint`** — the real, live OAuth 2.1 `client_credentials`
  token endpoint (`token_endpoint` in the RFC 8414 metadata above). There is
  no separate agent-identity-registration endpoint on AINative today, so this
  points at the token endpoint itself.
- **`identity_types_supported`** — only `service_auth` is listed. AINative's
  authorization server currently supports `client_credentials`
  (service-to-service auth) only. It does **not** yet support `identity_assertion`
  (ID-JAG-based, user-delegated agent identity) or `anonymous` registration
  through this OAuth flow — advertising either would overstate what the API
  actually does. When AINative adds ID-JAG support, this block will grow an
  `identity_assertion.assertion_types_supported` array; until then, don't
  expect one.

## Links

- Protected-resource metadata: `https://api.ainative.studio/.well-known/oauth-protected-resource`
- Authorization-server metadata: `https://api.ainative.studio/.well-known/oauth-authorization-server`
- Agent integration guide: `https://ainative.studio/agent.md`
- Machine-readable site guide: `https://ainative.studio/llms.txt`
- API documentation: `https://docs.ainative.studio`