sentryagent-idp/openspec/changes/archive/developer-docs-phase6-update/specs/ws2-concepts/spec.md

WS2 Spec — concepts.md

Target file

docs/developers/concepts.md

Objective

Add six new concept sections to the existing file. Do NOT modify any of the existing sections (What is AgentIdP?, What is an AI Agent Identity?, AGNTCY Alignment, Agent Lifecycle, OAuth 2.0 Client Credentials, Free Tier Limits). Append the new sections at the end of the file, each separated by a --- horizontal rule and preceded by a level-2 heading.

---

New section order (append after existing content)

1. Organizations and Multi-tenancy
2. DID Identity
3. OIDC Provider
4. A2A Delegation
5. API Tier Plans
6. AGNTCY Compliance

---

Section 1 — Organizations and Multi-tenancy

Heading: ## Organizations and Multi-tenancy

Content to write (3 paragraphs + table):

Paragraph 1: An organization is the top-level grouping unit in AgentIdP. Every registered agent can be scoped to an organization by including an organization_id in the agent registration request. Organizations have a unique slug (URL-safe identifier), a display name, and a planTier that controls per-org resource limits. All API operations that involve analytics, webhooks, tiers, and delegation are tenant-scoped: they only see data belonging to their organization.

Paragraph 2: Tenant isolation is enforced at the service layer. Every query involving multi-tenant data filters by organization_id. A token issued to an agent in org A cannot read data from org B. The organization_id is embedded in the JWT at token issuance time and validated on every request. This means you do not need to pass an org ID as a query parameter — it is derived automatically from the authenticated token.

Paragraph 3: When you create an organization, you define its slug. Slugs are immutable — once set, they cannot be changed. Choose a slug that matches your domain or product namespace, as it is used in DID identifiers for agents in that organization. Membership is managed through the POST /api/v1/organizations/{orgId}/members endpoint, which lets you add an existing agent to an organization with a member or admin role.

Table — org field reference:

Field	Type	Description
organizationId	UUID	System-assigned immutable identifier
name	string	Human-readable display name
slug	string	URL-safe unique identifier (immutable after creation)
planTier	enum	free | pro | enterprise
maxAgents	integer	Maximum active agents in this org
maxTokensPerMonth	integer	Maximum token issuances per month
status	enum	active | suspended | deleted

---

Section 2 — DID Identity

Heading: ## DID Identity

Content to write (3 paragraphs + DID structure example):

Paragraph 1: Every agent registered in AgentIdP automatically receives a Decentralized Identifier (DID) using the did:web method. A DID is a globally unique, self-describing identifier that does not rely on a central registry. The DID for an agent takes the form did:web:<host>:agents:<agentId> — for example, did:web:localhost%3A3000:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890. The did:web method means the DID document is resolvable via HTTPS: a resolver fetches https://<host>/api/v1/agents/<agentId>/did.

Paragraph 2: The DID Document is a JSON-LD object that describes the agent's cryptographic keys and service endpoints. It contains: the agent's DID as its id, a verificationMethod array with the agent's public key in JWK format, an authentication array referencing that key, and an agntcy extension object carrying agent metadata (type, capabilities, version, owner, deploymentEnv). This document is publicly accessible — no authentication required — so any external system can verify this agent's identity without contacting AgentIdP directly.

Paragraph 3: The did:web scheme was chosen because it is widely supported by DID resolvers, requires no blockchain, and leverages standard HTTPS infrastructure. When an external system receives a token from your agent, it can resolve your agent's DID, retrieve the public key from the DID Document, and independently verify the token's signature. This is the foundation of cross-system agent identity verification.

DID document structure diagram (Markdown code block):

DID Document structure for a registered agent
───────────────────────────────────────────────
{
  "@context": ["https://www.w3.org/ns/did/v1"],
  "id": "did:web:<host>:agents:<agentId>",
  "controller": "did:web:<host>:agents:<agentId>",
  "verificationMethod": [
    {
      "id": "<did>#key-1",
      "type": "JsonWebKey2020",
      "controller": "<did>",
      "publicKeyJwk": { "kty": "RSA", ... }
    }
  ],
  "authentication": ["<did>#key-1"],
  "agntcy": {
    "agentId": "<uuid>",
    "agentType": "screener",
    "capabilities": ["resume:read"],
    "deploymentEnv": "production",
    "owner": "talent-team",
    "version": "1.0.0"
  }
}

---

Section 3 — OIDC Provider

Heading: ## OIDC Provider

Content to write (3 paragraphs):

Paragraph 1: AgentIdP implements a subset of the OpenID Connect (OIDC) protocol, acting as an OIDC Provider for the agents it manages. This means AgentIdP publishes a standard discovery document at GET /.well-known/openid-configuration, which any OIDC-aware client can use to discover supported grant types, token endpoint, JWKS URI, and other metadata. It also exposes a JWKS endpoint at GET /.well-known/jwks.json for external systems to retrieve the public keys used to verify tokens.

Paragraph 2: The /agent-info endpoint is the equivalent of OIDC's UserInfo endpoint — it returns identity claims for the authenticated agent. External systems that receive a token issued by AgentIdP can call this endpoint (with that token) to retrieve the agent's verified identity attributes: its agentId, email, agentType, capabilities, and organization_id. This is particularly useful when a downstream service needs to verify the identity of an agent presenting a token, without duplicating identity data in its own store.

Paragraph 3: AgentIdP also supports OIDC token exchange for GitHub Actions. If you run your agent deployment workflows in GitHub Actions, you can configure a trust policy (POST /api/v1/oidc/trust-policies) that maps a GitHub repository and branch to an AgentIdP agent. The workflow can then exchange its GitHub OIDC JWT for an AgentIdP access token via POST /api/v1/oidc/token — no stored secrets required. This enables keyless, short-lived token issuance in CI/CD pipelines.

---

Section 4 — A2A Delegation

Heading: ## A2A Delegation

Content to write (3 paragraphs + flow diagram):

Paragraph 1: Agent-to-Agent (A2A) delegation allows one agent to grant another agent a subset of its own OAuth 2.0 scopes for a limited time. This is the building block for multi-agent pipelines where an orchestrator agent needs to delegate work to a specialist sub-agent without sharing its own full credentials. A delegation chain consists of: a delegator (the agent granting authority), a delegatee (the agent receiving authority), a set of scopes (must be a strict subset of the delegator's own scopes), and a TTL (60 seconds to 86,400 seconds).

Paragraph 2: The grant flow is straightforward: the delegator calls POST /api/v1/oauth2/token/delegate with the delegatee's agent ID, the scopes to grant, and the TTL. AgentIdP returns a signed delegation token. The delegatee presents this token when calling POST /api/v1/oauth2/token/verify-delegation to prove it has been granted authority. AgentIdP verifies the chain integrity and returns the delegation details including whether it is still valid. The delegator can revoke the chain at any time via DELETE /api/v1/oauth2/token/delegate/{chainId}.

Paragraph 3: Delegation is useful for: workflow handoffs between specialist agents, granting a monitoring agent read-only access to resources owned by a processing agent, and time-limited cross-agent authorization without credential sharing. Because delegation tokens are signed and verified server-side, a delegatee cannot extend the TTL, expand the scope, or pass the delegation to a third agent. The chain is always exactly two hops: delegator → delegatee.

Delegation flow (Markdown code block):

A2A Delegation Flow
───────────────────
1. Orchestrator (delegator) calls POST /api/v1/oauth2/token/delegate
   → body: { delegateeAgentId, scopes: ["agents:read"], ttlSeconds: 3600 }
   ← response: { delegationToken: "...", chainId: "...", expiresAt: "..." }

2. Orchestrator passes delegationToken to the sub-agent out-of-band

3. Sub-agent (delegatee) calls POST /api/v1/oauth2/token/verify-delegation
   → body: { delegationToken: "..." }
   ← response: { valid: true, scopes: ["agents:read"], expiresAt: "..." }

4. Sub-agent uses its own Bearer token + confirmed scope to act on behalf

5. (Optional) Orchestrator calls DELETE /api/v1/oauth2/token/delegate/{chainId}
   to revoke early

---

Section 5 — API Tier Plans

Heading: ## API Tier Plans

Content to write (3 paragraphs + table):

Paragraph 1: AgentIdP has three subscription tiers: Free, Pro, and Enterprise. Every organization is on one tier at a time. The tier determines the resource limits enforced at runtime: maximum number of active agents, maximum API calls per day, and maximum token issuances per day. When a limit is reached, the relevant operation returns a 403 FREE_TIER_LIMIT_EXCEEDED error until the next calendar day resets the counter (for daily limits) or until you upgrade your tier.

Paragraph 2: You can check your current tier, configured limits, and live usage at any time by calling GET /api/v1/tiers/status. The response shows your tier name, all three limit values, and the live usage counters for the current day. If you need higher limits, call POST /api/v1/tiers/upgrade with { "target_tier": "pro" } or "enterprise". This creates a Stripe Checkout Session and returns a one-time checkoutUrl. After payment, the organization's tier is updated automatically via Stripe webhook.

Paragraph 3: Enterprise tier limits are effectively unlimited (enforced as Infinity in the tier configuration). Enterprise customers should contact SentryAgent.ai to arrange billing and configure custom limits if needed. The maxAgents and maxTokensPerMonth fields on an organization record can be overridden at org creation or update to set tighter or looser limits than the tier defaults, regardless of tier.

Tier comparison table:

Limit	Free	Pro	Enterprise
Max agents	10	100	Unlimited
Max API calls / day	1,000	50,000	Unlimited
Max token issuances / day	1,000	50,000	Unlimited
Audit log retention	90 days	90 days	90 days
Webhooks	Yes	Yes	Yes
Analytics	Yes	Yes	Yes
A2A Delegation	Yes	Yes	Yes

---

Section 6 — AGNTCY Compliance

Heading: ## AGNTCY Compliance

Content to write (3 paragraphs):

Paragraph 1: AGNTCY is an open standard from the Linux Foundation that defines how AI agents should be identified, described, and governed across platforms. AgentIdP implements AGNTCY compliance in two ways: every agent automatically gets a DID and an agent card (a structured JSON object that describes the agent in the AGNTCY format), and AgentIdP can generate a compliance report that summarizes the verified state of all agents in a tenant. An agent card is the AGNTCY equivalent of a business card — it carries the agent's DID, type, capabilities, owner, version, and identity provider.

Paragraph 2: The compliance report (available at GET /api/v1/compliance/report) covers two dimensions: agent-identity verification (are all active agents reachable via their DID?) and audit-trail integrity (is the hash chain of audit events intact?). The report includes a boolean agntcyConformance field that summarizes whether the tenant meets AGNTCY baseline requirements. Reports are cached in Redis for 5 minutes; the X-Cache: HIT header signals a cached response.

Paragraph 3: For self-auditing and external audits, you can export all active agents as AGNTCY agent cards in bulk via GET /api/v1/compliance/agent-cards. This is an array of card objects that external compliance tools and AGNTCY-compatible registries can ingest directly. The GET /api/v1/compliance/controls endpoint (no authentication required) provides a live status snapshot of all SOC 2 Trust Services Criteria controls that AgentIdP monitors internally. These endpoints are gated by the COMPLIANCE_ENABLED environment variable; if disabled, they return 404.