ZeroID — Identity Infrastructure for AI Agents

ZeroID is open-source identity infrastructure for autonomous AI agents. It assigns agents SPIFFE-based identities (WIMSE URIs), issues OAuth 2.1 tokens, supports delegation chains via RFC 8693 token exchange, and manages credential policies. All operations use the REST API at

$ZEROID_BASE_URL

Authentication

All

/api/v1/*

Authorization

Authorization: Bearer $ZEROID_API_KEY

The

/oauth2/*

/health

1. Register an Agent

Create an agent identity with a WIMSE/SPIFFE URI and receive an API key. This is the recommended way to onboard agents — it atomically creates the identity record and issues a long-lived API key (

zid_sk_...

curl -s -X POST "$ZEROID_BASE_URL/api/v1/agents/register" \
  -H "Authorization: Bearer $ZEROID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Task Orchestrator",
    "external_id": "orchestrator-1",
    "sub_type": "orchestrator",
    "trust_level": "first_party",
    "created_by": "dev@company.com"
  }'

Response (201 Created):

{
  "identity": {
    "id": "uuid",
    "external_id": "orchestrator-1",
    "wimse_uri": "spiffe://auth.highflame.ai/acme/prod/agent/orchestrator-1"
  },
  "api_key": "zid_sk_..."
}

The

sub_type

orchestrator

autonomous

tool_agent

code_agent

trust_level

unverified

verified_third_party

first_party

To register a bare identity without an API key (for manual credential management):

curl -s -X POST "$ZEROID_BASE_URL/api/v1/identities" \
  -H "Authorization: Bearer $ZEROID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "data-fetcher-1",
    "trust_level": "unverified",
    "owner_user_id": "user-ops",
    "allowed_scopes": ["data:read", "data:write"]
  }'

2. Issue Credentials

Exchange OAuth2 client credentials for a short-lived JWT access token. First register an OAuth2 client, then use

client_credentials

Register an OAuth2 client:

curl -s -X POST "$ZEROID_BASE_URL/api/v1/oauth/clients" \
  -H "Authorization: Bearer $ZEROID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "my-agent-client",
    "name": "my-agent-client",
    "confidential": true,
    "grant_types": ["client_credentials"],
    "scopes": ["data:read", "data:write"]
  }'

Response (201 Created):

{
  "client": {
    "client_id": "my-agent-client"
  },
  "client_secret": "..."
}

Issue a token via client_credentials:

curl -s -X POST "$ZEROID_BASE_URL/oauth2/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "my-agent-client",
    "client_secret": "<client_secret>",
    "scope": "data:read"
  }'

Response (200 OK):

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "data:read"
}

ZeroID also supports

api_key

jwt_bearer

authorization_code

refresh_token

/oauth2/token

3. Delegate to Sub-Agent

Use RFC 8693 token exchange to delegate a subset of the orchestrator's permissions to a sub-agent. Scope is automatically attenuated — the sub-agent can only receive scopes the parent already holds.

curl -s -X POST "$ZEROID_BASE_URL/oauth2/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "subject_token": "<orchestrator_access_token>",
    "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "actor_token": "<sub_agent_jwt_assertion>",
    "actor_token_type": "urn:ietf:params:oauth:token-type:jwt",
    "scope": "data:read"
  }'

Response (200 OK):

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "expires_in": 3600,
  "scope": "data:read"
}

The delegated token carries the full chain:

sub

act.sub

delegation_depth

actor_token

Multi-hop delegation is supported — a sub-agent can delegate further to a tool agent.

CredentialPolicy.max_delegation_depth

4. Revoke Credentials

Revoke a credential immediately. Revocation cascades — revoking an orchestrator's credential invalidates all downstream delegated tokens in the chain.

curl -s -X POST "$ZEROID_BASE_URL/api/v1/credentials/{credential_id}/revoke" \
  -H "Authorization: Bearer $ZEROID_API_KEY" \
  -H "Content-Type: application/json"

Response (200 OK):

{
  "revoked": true,
  "id": "uuid"
}

You can also revoke a token directly via the OAuth2 revocation endpoint (RFC 7009):

curl -s -X POST "$ZEROID_BASE_URL/oauth2/token/revoke" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "<access_token>"
  }'

To deactivate an entire agent (revokes all its tokens):

curl -s -X DELETE "$ZEROID_BASE_URL/api/v1/agents/registry/{agent_id}" \
  -H "Authorization: Bearer $ZEROID_API_KEY"

5. Credential Policies

Create governance templates that enforce TTL limits, allowed grant types, required trust levels, and maximum delegation depth. Policies are assigned to API keys and enforced at token issuance time.

curl -s -X POST "$ZEROID_BASE_URL/api/v1/credential-policies" \
  -H "Authorization: Bearer $ZEROID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "restricted-agent-policy",
    "description": "Policy for restricted tool agents",
    "max_ttl_seconds": 1800,
    "allowed_grant_types": ["api_key", "client_credentials"],
    "allowed_scopes": ["data:read", "tools:read"],
    "required_trust_level": "first_party",
    "max_delegation_depth": 1
  }'

Response (201 Created):

{
  "id": "uuid",
  "name": "restricted-agent-policy",
  "max_ttl_seconds": 1800,
  "allowed_grant_types": ["api_key", "client_credentials"],
  "allowed_scopes": ["data:read", "tools:read"],
  "required_trust_level": "first_party",
  "max_delegation_depth": 1,
  "is_active": true
}

Get a policy:

curl -s "$ZEROID_BASE_URL/api/v1/credential-policies/{policy_id}" \
  -H "Authorization: Bearer $ZEROID_API_KEY"

Update a policy:

curl -s -X PATCH "$ZEROID_BASE_URL/api/v1/credential-policies/{policy_id}" \
  -H "Authorization: Bearer $ZEROID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "max_delegation_depth": 3
  }'

6. Health Check

Verify the ZeroID server is running and healthy. No authentication required.

curl -s "$ZEROID_BASE_URL/health"

Response (200 OK):

{
  "status": "healthy",
  "service": "zeroid",
  "timestamp": "2026-01-01T00:00:00Z"
}

Readiness check (includes database connectivity):

curl -s "$ZEROID_BASE_URL/ready"

Additional Endpoints

/api/v1/agents/registry

/api/v1/agents/registry/{id}

/api/v1/agents/registry/{id}

/api/v1/identities/{id}

/api/v1/identities

/oauth2/token/introspect

/oauth2/token/verify

/.well-known/jwks.json

/.well-known/oauth-authorization-server

/api/v1/attestations

/api/v1/proofs/generate

/api/v1/proofs/verify

/api/v1/signals/ingest

Resources

• ZeroID GitHub
• Quickstart Notebook
• Interactive API docs (or

  GET /docs

  when running locally)