Skip to main content

Agent Authentication

How an autonomous AI agent authenticates to the ZeroDB / AINative API — both for direct developer use today, and for standards-based, scoped delegation on behalf of a human user.

1. Direct API-key authentication (works today)

The simplest, fully-working path for a developer or an agent they control directly.

Every request to the ZeroDB API can be authenticated with a single header:

curl https://api.ainative.studio/v1/vectors/search \
  -H "X-API-Key: <your_api_key>"

This is unscoped — the key carries the full permissions of the account it belongs to. It is the right choice when a human developer is calling the API themselves, or running their own agent under their own account. It is not a standards-based delegation mechanism for a third-party agent acting on a different user's behalf, which is what the rest of this page covers.

2. OAuth 2.1 discovery and scoped tokens (live)

AINative's authorization server publishes standard OAuth 2.0 / OIDC discovery metadata and issues real, scoped, time-limited bearer tokens.

An agent can discover how to authenticate without a human in the loop by walking the standard discovery chain:

  • GET https://api.ainative.studio/.well-known/oauth-protected-resource — RFC 9728, names the authorization server
  • GET https://api.ainative.studio/.well-known/oauth-authorization-server — RFC 8414, publishes the real token_endpoint and grant_types_supported
  • GET https://api.ainative.studio/.well-known/openid-configuration — standard OIDC discovery document

Exchange a client_id/client_secret pair for a scoped access token via the standard OAuth 2.1 client-credentials grant:

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, expires_in, and the granted scope. Tokens can be introspected (POST /api/v1/cloud/auth/token/introspect, RFC 7662) or revoked (POST /api/v1/cloud/auth/token/revoke, RFC 7009).

The full list of declared scopes is published live at GET https://api.ainative.studio/api/v1/cloud/auth/scopes:

zerodb.read
zerodb.write
zerodb.admin
memory.recall
memory.store
memory.forget
mcp.connect
mcp.execute
file.upload
file.download
agent.delegate
agent.register

3. Agent acting on behalf of a human (identity claim flow)

A WorkOS auth.md-style ceremony for an autonomous agent to get a credential a specific human has approved, without that human pre-provisioning an OAuth client.

This is the flow most relevant to "an agent acting on a user's behalf":

  1. The agent self-registers: POST https://api.ainative.studio/agent/identity with {"type": "anonymous"}. The response includes a claim_url and claim_token.
  2. The human user opens the claim_url while signed in and approves the agent via POST https://api.ainative.studio/agent/claim, binding the pending registration to their account.
  3. The agent polls the standard token endpoint with a non-standard grant type for this ceremony (grant_type=urn:workos:agent-auth:grant-type:claim) until it returns authorization_pending → a real scoped access_token once claimed.
  4. If the user's credentials change, AINative can push a revocation event to POST https://api.ainative.studio/agent/events (RFC 8417 Security Event Token).

Current limitation — please read before integrating

The OAuth 2.1 client-credentials grant, the scoped-token lifecycle (issue / introspect / revoke / delegate), and the identity-claim ceremony above are real and live today — every endpoint and curl example on this page works against the production API.

What is not yet true: scopes issued by this system (zerodb.read, zerodb.write, etc.) are not yet enforced as the authorization check on ZeroDB's own data-plane routes (vectors, tables, files, memory, PostgreSQL). Those routes currently authorize via API key or user session only. Scope enforcement on the data plane, and a full authorization_code/PKCE consent-screen flow for interactive third-party agents, are tracked separately in core#9821. Do not rely on an OAuth-issued scope alone to restrict what an agent can touch on ZeroDB resources until that lands.

Reference

ZeroDB — part of AINative Studio