Agent Identity API

The Agent Identity API provides cryptographic identity for agents -- enabling authentication, delegation, and access control across agent-to-agent interactions.

What the Identity System Provides

Capability	Description
Client Metadata	IETF-standard identity document for each agent
JWKS	Public key sets for verifying agent signatures
SPIFFE Identity	Trust-domain-scoped identity for zero-trust architectures
JWT-SVID	Short-lived identity tokens for cross-service authentication
Token Exchange	RFC 8693 delegation -- one agent requests scoped access to another
ExtAuthZ (TBAC)	Tool-Based Access Control enforcement for delegated tool calls
Verifiable Credentials	W3C VC 2.0 badges proving agent capabilities

Token Types

typ Header	Token Type	Purpose
JWT	SVID	Identity proof
vc+jwt	Badge	Capability proof
at+jwt	Access Token	Delegation proof

All tokens use ES256 (ECDSA P-256) and can be verified against the platform's public trust bundle.

Audience Formats

The audience parameter accepts three formats, all resolving to the same agent:

Format	Example
SPIFFE ID	spiffe://meetloyd.com/tenant/t1/agent/agent-b
Client ID URL	https://api.meetloyd.com/api/v1/identity/agents/agent-b/client-metadata.json
Bare agent ID	agent-b

Public Endpoints

These endpoints require no authentication. They serve the agent's public identity documents.

Get Client Metadata

GET /api/v1/identity/agents/{agentId}/client-metadata.json

Returns the IETF Client ID Metadata document including OAuth grant types, JWKS URI, SPIFFE ID, and signed VC badge.

Get Agent JWKS

GET /api/v1/identity/agents/{agentId}/jwks.json

Returns the agent's JSON Web Key Set (EC P-256 public keys).

Get Platform JWKS

GET /api/v1/identity/.well-known/jwks.json

Returns MeetLoyd's platform-level public keys for verifying Badges, SVIDs, and exchanged tokens. Cached for 1 hour.

Get SPIFFE Trust Bundle

GET /.well-known/spiffe/trust-bundle

Returns the SPIFFE Trust Bundle with sequence number and refresh hint (300s recommended). Used for verifying JWT-SVIDs.

Token Exchange (RFC 8693)

POST /api/v1/identity/oauth/token

Exchanges a subject token (SVID) for a scoped access token for delegation. The subject token serves as authentication.

Required parameters: grant_type (must be urn:ietf:params:oauth:grant-type:token-exchange), subject_token, subject_token_type, audience (target agent), scope (space-separated tools:* scopes).

Returns an at+jwt access token with the requested tool scopes, delegation chain (act claim), and 1-hour expiry.

Error codes: unsupported_grant_type, invalid_request, invalid_grant (bad token), invalid_target (agent not found or cross-tenant), invalid_scope, insufficient_scope, server_error.

ExtAuthZ (TBAC Enforcement)

POST /api/v1/identity/authorize

Verifies whether a delegated tool call should be allowed. The exchanged token serves as authentication.

Parameters: token (access token), tool (tool name), callee (callee agent ID).

Returns allowed: true/false with a reason code indicating the policy decision.

Possible reasons: token_invalid, tool_not_in_scope, policy_allow, policy_deny, no_policy_audit_allow, no_policy_enforce_deny.

Authenticated Endpoints

These require a JWT bearer token.

Issue JWT-SVID

POST /api/v1/identity/agents/{agentId}/svid (requires agents:write)

Issue a short-lived SPIFFE JWT-SVID. Parameters: audience (required), ttlSeconds (default 3600, max 86400).

Rotate Agent Key

POST /api/v1/identity/agents/{agentId}/keys/rotate (requires agents:write)

Generates a new EC P-256 key pair. The old key is marked as rotated.

Revoke Agent Key

DELETE /api/v1/identity/agents/{agentId}/keys/{keyId} (requires agents:write)

Revokes a specific key. Key-agent binding is enforced.

Token Introspection (RFC 7662)

POST /api/v1/identity/oauth/introspect (requires agents:read)

Verify and inspect an exchanged access token. Returns active: true with full claims, or active: false for invalid tokens. Per RFC 7662, always returns 200 OK.

TBAC Policy Management

List Policies

GET /api/v1/identity/tbac/policies (requires settings:read)

Filter by callerAgentId, calleeAgentId, toolName. Supports pagination.

Create Policy

POST /api/v1/identity/tbac/policies (requires settings:write)

Field	Type	Required	Description
callerAgentId	string	Yes	Caller agent ID or * for any
calleeAgentId	string	Yes	Callee agent ID or * for any
toolName	string	Yes	Tool name or * for any
effect	string	No	allow (default) or deny
description	string	No	Human-readable description

Returns 409 if a policy already exists for the same (caller, callee, tool) combination.

Update Policy

PATCH /api/v1/identity/tbac/policies/{id} (requires settings:write)

Update effect, conditions, or description. All fields optional.

Delete Policy

DELETE /api/v1/identity/tbac/policies/{id} (requires settings:write)

Verifying Tokens Externally

To verify any MeetLoyd-signed token from an external system:

1. Fetch the trust bundle from GET /.well-known/spiffe/trust-bundle
2. Verify the JWT signature against the keys
3. Check the typ header to determine token type (JWT, vc+jwt, at+jwt)
4. Validate iss (should be https://meetloyd.com) and exp (expiry)
5. Check aud to verify your identity is in the audience list