Agent Key Management

Agent keys are the machine credentials that identify an AI agent in the Syndicate Links attribution system. Proper key management — issuance, storage, rotation, and scoping — is critical for maintaining attribution integrity and preventing unauthorized commission claims.

Key Types

Syndicate Links uses a two-tier key hierarchy:

Account Keys

Account keys authenticate the publisher account and provide access to account-level operations: creating agent keys, configuring payouts, viewing reports, and managing program enrollments.

• Prefix: pub_
• Scope: Full account access
• Typical holder: The developer or organization operating the agent
• Storage: Secure backend, CI/CD secrets, never in agent runtime

Agent Keys

Agent keys authenticate individual agent identities for attribution operations. Each agent deployment should have its own key.

• Prefix: aff_agent_
• Scope: Attribution events and commission queries only
• Typical holder: The agent runtime (environment variable, secret manager)
• Storage: Agent configuration, secret manager, environment variable

The separation matters: if an agent key is compromised, the attacker can submit fraudulent attribution events but cannot access account settings, create new keys, or initiate payouts. The blast radius is contained.

Key Issuance

Agent keys are created through the account API using an account key:

curl -X POST https://api.syndicatelinks.co/v1/agent-keys \
  -H "Authorization: Bearer pub_account_key" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "shopping-agent-prod",
    "metadata": {
      "runtime": "langchain",
      "deployment": "production",
      "version": "2.1.0"
    }
  }'

Response:

{
  "agent_key": "aff_agent_abc123",
  "agent_secret": "sk_agent_xyz789",
  "label": "shopping-agent-prod",
  "created_at": "2026-04-04T10:00:00Z",
  "status": "active"
}

The agent_secret is returned only at creation time. Store it immediately in your secret manager — it cannot be retrieved later.

Storage Best Practices

Environment Variables

The simplest approach for single-agent deployments:

export SL_AGENT_KEY=aff_agent_abc123
export SL_AGENT_SECRET=sk_agent_xyz789

Secret Managers

For production deployments, use your platform's secret manager:

• AWS Secrets Manager — store as a JSON secret with agent_key and agent_secret fields
• Google Secret Manager — version-controlled secrets with automatic rotation triggers
• HashiCorp Vault — dynamic secrets with TTL-based rotation
• macOS Keychain — security add-generic-password -s "sl-agent-key" -a "agent-name" -w "key_value"

Never Store In

• Source code repositories (even private ones)
• Agent prompt text or system messages
• Client-side code or browser-accessible locations
• Unencrypted configuration files
• Log output or error messages

Key Rotation

Agent keys should be rotated periodically and immediately if a compromise is suspected.

Rotation Flow

1. Create a new agent key via the account API
2. Update the agent's runtime configuration with the new key
3. Verify the new key works by submitting a test attribution event
4. Deactivate the old key via the account API

# Deactivate old key
curl -X PATCH https://api.syndicatelinks.co/v1/agent-keys/aff_agent_old_key \
  -H "Authorization: Bearer pub_account_key" \
  -H "Content-Type: application/json" \
  -d '{"status": "inactive"}'

Rotation Schedule

Deactivated keys reject new attribution events but do not affect previously recorded commissions.

Key Scoping

For organizations operating multiple agents, each agent should have its own key. This provides:

• Per-agent attribution — commission reports can be broken down by individual agent
• Independent rotation — one agent's key can be rotated without affecting others
• Granular revocation — a compromised agent can be isolated without disrupting the fleet
• Audit trail — every attribution event is tied to a specific agent identity

Multi-Agent Example

Organization: Acme AI Corp (pub_acme)
├── Shopping Agent (aff_agent_shop_prod)
├── Support Agent (aff_agent_support_prod)
├── Docs Agent (aff_agent_docs_prod)
└── Research Agent (aff_agent_research_staging)

Each agent reports commission independently. The organization sees aggregate and per-agent breakdowns in their account dashboard and API reports.

Key Lifecycle States

Related Docs

• How Agent Attribution Works — the full technical spec including key hierarchy
• Signed Attribution Tokens (SLAT) — how agent keys are used to sign attribution tokens
• Getting Started — set up your account and issue your first agent key