Agent Authentication (SPIFFE)

Subnoto supports SPIFFE-based machine identity for AI agents and automated services. Instead of sharing API key secrets, your agents authenticate with short-lived JWT SVIDs issued by your own SPIRE infrastructure — verified inside Subnoto’s confidential enclave.

Why SPIFFE?

Aspect	API Keys	SPIFFE Agent Auth
Credential type	Static secret (access key + secret key)	Short-lived JWT SVID (auto-rotated)
Rotation	Manual	Automatic (via SPIRE)
Identity	Opaque key ID	Cryptographic identity (spiffe://your-domain/…)
Audit trail	Key ID in logs	Full SPIFFE ID in logs
Revocation	Delete key	Suspend/revoke registration, or stop issuing SVIDs

SPIFFE is ideal when you run workloads in Kubernetes, VMs, or any environment with a SPIRE agent — your services get identity automatically without managing secrets.

How it works

1. SPIRE issues a JWT SVID to your agent (automatically, via the Workload API)
2. Your agent sends API requests with the JWT as a Bearer token
3. Subnoto’s enclave verifies the JWT signature against the trust bundle you registered
4. Permissions are enforced — the agent can only perform actions you allowed

Quick start

1. Register an agent

Go to Settings > Agent Registrations and click Register Agent. You’ll need:

• Name — A human-readable label (e.g. “Production NDA Signer”)
• Trust Domain — Your SPIFFE trust domain (e.g. acmecorp.com)
• SPIFFE ID — The exact SPIFFE ID your agent will present (e.g. spiffe://acmecorp.com/ns/prod/sa/nda-signer)
• Trust Bundle — The JWKS containing your SPIRE server’s public keys. You can either:
  • Fetch from a URL — Provide your SPIRE server’s JWKS endpoint or OIDC discovery URL (e.g. https://spire.acmecorp.com/.well-known/openid-configuration). Subnoto fetches the keys automatically.
  • Paste manually — Paste the JWKS JSON directly.
• Permissions — Select which API actions the agent is allowed to perform (same CASL permission model as API keys).

2. Configure your agent

Your agent needs to send its JWT SVID as a Bearer token in the Authorization header:

Authorization: Bearer <JWT_SVID>

MCP Server

The Subnoto MCP server supports SPIFFE authentication natively. Configure it with environment variables:

Using SPIRE Workload API (recommended):

docker run -i --rm \
  -v /run/spire/sockets:/spiffe-workload-api \
  -e SPIFFE_ENDPOINT_SOCKET=/spiffe-workload-api/api.sock \
  -e SPIFFE_AUDIENCE=subnoto.com \
  subnoto/mcp-server:latest

The MCP server automatically fetches and refreshes JWT SVIDs from the SPIRE agent.

Using a JWT SVID file (rotated externally through the spire sidecar):

docker run -i --rm \
  -v /path/to/svid.jwt:/svid.jwt \
  -e SPIFFE_JWT_SVID_PATH=/svid.jwt \
  subnoto/mcp-server:latest

3. Verify it works

Use the utils_whoami MCP tool to confirm your agent is authenticated. The response will include an agent field with your SPIFFE ID.

Permissions

Agent permissions use the same model as API keys. When registering an agent, you select which actions it can perform:

Permission	Description
Read	List and retrieve resources
Create	Create new resources
Update	Modify existing resources
Delete	Delete resources
Manage	Full access (includes all above)

Permissions are scoped per resource type (Template, Envelope, Contact, Workspace, Team, Webhook).

Suspending and revoking

• Suspend — Temporarily disable an agent. The registration remains and can be reactivated.
• Revoke — Permanently disable an agent. This cannot be undone. The agent’s SPIFFE ID can be re-registered with a new registration.

Next steps

API Keys

MCP Server

Encryption Proxy