Store Encrypted Agent Credentials as Auth Contexts

Register encrypted auth contexts to store bearer tokens and API keys for agents. Reference them by ID at invocation time instead of passing raw tokens.

Auth contexts let you register encrypted credential references on ServiceNet. Instead of passing a raw bearer token or API key on every invocation, you store the credential once and reference it by auth_context_id. Tokens are encrypted at rest with ChaCha20-Poly1305 — only a masked preview is ever exposed in API responses, making auth contexts safe to log and inspect without leaking secrets.

When to use auth contexts

Consider storing credentials as auth contexts when:

• You want to avoid embedding tokens in client code, request logs, or orchestration configs
• You invoke the same agent repeatedly from multiple callers that share a credential
• You want to manage and rotate credentials centrally without redeploying callers

Register an auth context

Send a POST to /v1/auth-contexts/register with the credential details. The provider_id you supply must match the provider that owns the target agent — the gateway enforces this at invocation time.

curl -X POST http://127.0.0.1:8042/v1/auth-contexts/register \
  -H 'content-type: application/json' \
  -d '{
    "subject_did": "did:key:z6MkhaXgBZDvotD1X9gRrYkM5Xq9jYQqK6d8r8bQdE1mV2Xa",
    "provider_id": "acme-labs",
    "auth_model": { "mode": "bearer_token" },
    "token": "my-secret-api-key"
  }'

ServiceNet encrypts the token, stores a secret_ref UUID pointing to the encrypted blob, and returns the new AuthContextRecord:

{
  "auth_context_id": "550e8400-e29b-41d4-a716-446655440000",
  "secret_ref": "b3a9f120-4c2d-4e8a-9f1b-7d3c5e6a8b2d",
  "subject_did": "did:key:z6MkhaXgBZDvotD1X9gRrYkM5Xq9jYQqK6d8r8bQdE1mV2Xa",
  "provider_id": "acme-labs",
  "auth_model": { "mode": "bearer_token" },
  "token_preview": "my-se***",
  "created_at": "2025-01-15T10:00:00Z"
}

token_preview shows only the first few characters of the original token followed by asterisks. The full token is never returned in any API response after registration.

Request fields

subject_did · string · required

The DID of the credential owner — typically the agent caller or the identity asserting ownership of this credential.

provider_id · string · required

The provider this credential is scoped to. Must match the provider_id of any agent you intend to invoke using this auth context. The gateway rejects invocations where the auth context provider does not match the target agent’s provider.

auth_model · object · required

Describes how the credential will be injected into downstream A2A calls. See Auth model options below.

token · string · required

The plaintext credential to encrypt and store. This value is encrypted immediately on write and is never stored or returned in plaintext.

expires_at · string

Optional ISO 8601 timestamp. If set, the gateway rejects invocations that reference this auth context after the expiry time, returning HTTP 403.

Auth model options

Show Supported auth models

Mode	JSON	Description
none	{ "mode": "none" }	No credential is injected. Use this when the target agent is public.
bearer_token	{ "mode": "bearer_token" }	The token is sent as an HTTP Authorization: Bearer <token> header on the downstream A2A call.
api_key_header	{ "mode": "api_key_header", "header_name": "X-API-Key" }	The token is sent in the custom header you specify. Replace X-API-Key with your target agent’s expected header name.
capability_token	{ "mode": "capability_token" }	A capability-based token scoped to a specific permission or resource. Injected as a bearer token.

Use an auth context in invocations

Pass auth_context_id in place of auth_token when calling /v1/agents/:agent_id/invoke. The gateway resolves the stored credential, decrypts it, and injects it into the downstream A2A call automatically.

curl -X POST http://127.0.0.1:8042/v1/agents/stripe-agent/invoke \
  -H 'content-type: application/json' \
  -d '{
    "message": "Create a payment link",
    "auth_context_id": "550e8400-e29b-41d4-a716-446655440000",
    "region": "AU"
  }'

If you supply both auth_token and auth_context_id, the auth context takes precedence. The gateway resolves the stored credential first and uses it as the effective token.

The provider_id on the auth context must match the provider that owns the agent you are invoking. If they differ, the gateway returns HTTP 403 with "auth context provider does not match target provider".

List auth contexts

Retrieve all registered auth contexts, optionally filtered by provider_id or subject_did:

# Filter by provider
curl 'http://127.0.0.1:8042/v1/auth-contexts?provider_id=acme-labs'

# Filter by subject DID
curl 'http://127.0.0.1:8042/v1/auth-contexts?subject_did=did:key:z6MkhaXgBZDvotD1X9gRrYkM5Xq9jYQqK6d8r8bQdE1mV2Xa'

The response wraps results in an items array. Each item is an AuthContextRecord with token_preview instead of the plaintext token.

Node configuration

Auth contexts require SERVICENET_SECRET_BROKER_KEY to be set on the node. This must be a base64-encoded 32-byte key used to derive the ChaCha20-Poly1305 encryption key. Without it, any database-backed deployment will refuse to start, and auth context registration will fail.

Generate a key with:

openssl rand -base64 32

Then pass it as an environment variable when starting the node:

SERVICENET_SECRET_BROKER_KEY=<your-base64-key> cargo run -p watt-servicenet-node