Delegated Agent Authorization Protocol (DAAP)

1.1. Requirements Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

1.2. Terminology

The following terms are used throughout this document:¶

Agent:

An AI-powered software process that takes autonomous actions on behalf of a Principal. An Agent has a persistent cryptographic identity (DID) and must obtain an explicit grant from its Principal before acting on their behalf.¶

Principal:

The human user who authorizes an Agent to act on their behalf. The Principal is the subject (sub) of any Grant Token issued by the authorization server.¶

Developer:

The organization or individual who built and operates the Agent. The Developer authenticates to the authorization server using an API key.¶

Authorization Server:

A server implementing this specification that issues Grant Tokens, maintains the grant registry, and provides the JWKS endpoint for offline verification.¶

Service:

Any API or platform that receives requests from an Agent. Services MUST verify Grant Tokens before acting on agent requests.¶

Grant:

A persistent record of permission given by a Principal to an Agent for a specific set of Scopes. A Grant is represented to the Agent as a Grant Token.¶

Grant Token:

A signed JWT [RFC7519] representing a valid, non-revoked Grant. Grant Tokens are short-lived credentials carrying agent-specific claims defined in Section 5.¶

Scope:

A named permission string following the format resource:action[:constraint] as defined in Section 3.¶

DID:

A Decentralized Identifier [DID-CORE] — the Agent's cryptographic identity. In DAAP, Agent DIDs take the form did:grantex:<agent_id>.¶

Policy:

A rule evaluated by the Policy Engine (Section 10) that automatically approves or denies an authorization request before the consent UI is shown to the Principal.¶

Anomaly:

A behavioral deviation from an agent's established activity baseline, detected by the runtime monitoring system defined in Section 11.¶

2.1. DID Format

Every Agent registered with a DAAP-compliant Authorization Server receives a Decentralized Identifier of the form:¶

did:grantex:<agent_id>

where <agent_id> is a ULID (Universally Unique Lexicographically Sortable Identifier) [ULID] prefixed with ag_.¶

Example:¶

did:grantex:ag_01HXYZ123abcDEF456ghi

2.2. Identity Document

The DID resolves to an identity document at the Authorization Server. The document MUST contain the following fields:¶

{
  "@context": "https://grantex.dev/v1/identity",
  "id": "did:grantex:ag_01HXYZ123abcDEF456ghi",
  "developer": "org_yourcompany",
  "name": "travel-booker",
  "description": "Books flights and hotels on behalf of users",
  "declaredScopes": ["calendar:read", "payments:initiate:max_500"],
  "status": "active",
  "createdAt": "2026-02-01T00:00:00Z",
  "verificationMethod": [{
    "id": "did:grantex:ag_01HXYZ123abcDEF456ghi#key-1",
    "type": "JsonWebKey2020",
    "publicKeyJwk": { "..." : "..." }
  }]
}

2.3. Key Management

Authorization Servers MUST adhere to the following key management requirements:¶

• Authorization Servers MUST use RS256 (RSASSA-PKCS1-v1_5 using SHA-256) [RFC7518] for signing Grant Tokens.¶

• Private signing keys MUST never be transmitted or stored outside the Authorization Server's trust boundary.¶

• Public keys MUST be published at /.well-known/jwks.json as a JWK Set [RFC7517].¶

• Key rotation MUST be supported without changing the Agent's DID or invalidating existing, unexpired Grant Tokens. Rotated keys MUST remain in the JWKS until all tokens signed with them have expired.¶

3.1. Format

Scopes are permission strings of the form:¶

resource:action[:constraint]

where:¶

• resource identifies the data or service being accessed (e.g., calendar, payments, email)¶

• action identifies the operation (e.g., read, write, send, initiate, delete)¶

• constraint is an optional limiting parameter (e.g., max_500 for a spending limit)¶

3.2. Standard Scope Registry

The following scopes constitute the normative standard registry. Implementations MUST support all standard scopes that are relevant to the resources they expose:¶

3.3. Custom Scopes

Services MAY define custom scopes using reverse-domain notation per [RFC3986]:¶

com.stripe.charges:create:max_5000
io.github.issues:create

Custom scopes MUST use reverse-domain notation to avoid collisions with the standard registry.¶

3.4. Scope Display Requirements

Authorization Servers MUST maintain a human-readable description for each scope in their registry. Consent UIs MUST display human-readable descriptions to Principals, never raw scope strings.¶

4.1. Overview

The DAAP grant flow is modelled on the OAuth 2.0 Authorization Code flow [RFC6749] with the following adaptations: the client is always a Developer (identified by an API key), the resource owner is a Principal identified by the Developer's internal user identifier, and the resulting token carries agent-specific claims.¶

Developer App          Authorization Server       Principal
     |                         |                      |
     | POST /v1/authorize       |                      |
     | {agentId, principalId,  |                      |
     |  scopes, redirectUri}    |                      |
     |------------------------>|                      |
     |                         |                      |
     |<------------------------|                      |
     | {authRequestId,          |                      |
     |  consentUrl}             |                      |
     |                         |                      |
     | redirect user --------------------------------->|
     |                         | consent UI displayed |
     |                         |<---------------------|
     |                         | Principal approves   |
     |                         |                      |
     |<------------------------------------------------|
     | redirectUri?code=AUTH_CODE                      |
     |                         |                      |
     | POST /v1/token           |                      |
     | {code, agentId}          |                      |
     |------------------------>|                      |
     |<------------------------|                      |
     | {grantToken,             |                      |
     |  refreshToken}           |                      |

4.2. Authorization Request

The Developer initiates the flow by sending:¶

POST /v1/authorize
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "agentId": "ag_01HXYZ123abc",
  "principalId": "user_abc123",
  "scopes": ["calendar:read", "payments:initiate:max_500"],
  "expiresIn": "24h",
  "redirectUri": "https://yourapp.com/auth/callback",
  "state": "<csrf_token>",
  "audience": "https://api.targetservice.com"
}

The audience field is OPTIONAL. When present, it MUST be embedded as the aud claim in the issued Grant Token. The state parameter is REQUIRED and MUST be validated by the Developer's callback handler to prevent CSRF attacks. The redirectUri MUST match a URI pre-registered for the Agent at the Authorization Server.¶

Authorization Servers MUST reject requests whose redirectUri does not exactly match a pre-registered value for the specified agentId.¶

Response 200 OK:¶

{
  "authRequestId": "areq_01HXYZ...",
  "consentUrl": "https://consent.example.com/authorize?req=eyJ...",
  "expiresAt": "2026-02-01T00:15:00Z"
}

4.3. Consent UI Requirements

Authorization Servers MUST render a consent UI to the Principal that displays all of the following before the Principal approves or denies:¶

1. The Agent's registered name and description¶

2. The Developer's registered organization name¶

3. The full list of requested scopes with human-readable descriptions¶

4. The token expiry period¶

5. A prominent deny/cancel action that is at least as visually prominent as the approve action¶

4.4. Token Exchange

After Principal approval, the Authorization Server calls redirectUri?code=AUTH_CODE&state=STATE.¶

POST /v1/token
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "code": "AUTH_CODE",
  "agentId": "ag_01HXYZ123abc"
}

Response 200 OK:¶

{
  "grantToken": "eyJhbGciOiJSUzI1NiJ9...",
  "refreshToken": "ref_01HXYZ...",
  "grantId": "grnt_01HXYZ...",
  "scopes": ["calendar:read", "payments:initiate:max_500"],
  "expiresAt": "2026-02-02T00:00:00Z"
}

Refresh tokens are single-use. The Authorization Server MUST rotate the refresh token on every use. Refresh tokens MUST be invalidated when the underlying Grant is revoked.¶

5.1. JOSE Header

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "<key_id>"
}

The alg field MUST be RS256. Authorization Servers MUST NOT issue tokens with any other algorithm. Verifiers MUST explicitly reject tokens with any alg value other than RS256, including none and HS256.¶

5.2. JWT Claims

{
  "iss": "https://as.example.com",
  "sub": "user_abc123",
  "aud": "https://api.targetservice.com",
  "agt": "did:grantex:ag_01HXYZ123abc",
  "dev": "org_yourcompany",
  "grnt": "grnt_01HXYZ...",
  "scp": ["calendar:read", "payments:initiate:max_500"],
  "iat": 1709000000,
  "exp": 1709086400,
  "jti": "tok_01HXYZ987xyz"
}

The following claims are defined by this specification:¶

5.3. Token Validation

Services receiving a Grant Token MUST verify all of the following:¶

1. The token signature is valid, verified using the JWK Set published at {iss}/.well-known/jwks.json, with the key identified by kid.¶

2. The alg header value is RS256. Tokens with any other alg MUST be rejected.¶

3. The exp claim has not passed (allowing for a reasonable clock skew of no more than 300 seconds).¶

4. If the service has a registered audience identifier, the aud claim matches that identifier.¶

5. The scp array contains all scopes required for the requested operation.¶

6. For high-stakes operations (see Section 5.4), the token has not been revoked via the online verification endpoint.¶

5.4. Token Lifetime Guidance

Implementations caching revocation state MUST NOT cache for longer than 300 seconds (5 minutes). Services processing high-stakes scopes (payments:initiate, email:send, files:write) SHOULD perform online verification for each token use.¶

6.1. Revoke a Grant

DELETE /v1/grants/{grantId}
Authorization: Bearer <principal_token>

Effect: all active Grant Tokens issued under this Grant are immediately invalidated. The Grant record is marked revoked with a timestamp.¶

6.2. Revoke a Specific Token

POST /v1/tokens/revoke
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "jti": "tok_01HXYZ987xyz"
}

Response: 204 No Content.¶

6.3. Online Verification

POST /v1/tokens/verify
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "token": "eyJhbGciOiJSUzI1NiJ9..."
}

Response 200 OK:¶

{
  "valid": true,
  "grantId": "grnt_01HXYZ...",
  "scopes": ["calendar:read"],
  "principal": "user_abc123",
  "agent": "did:grantex:ag_01HXYZ123abc",
  "expiresAt": "2026-02-02T00:00:00Z"
}

6.4. JTI Replay Prevention

Authorization Servers MUST track all issued jti values for the lifetime of the corresponding token. If a jti value is presented for verification more than once within its validity window, the Authorization Server MUST return valid: false and SHOULD log an anomaly event.¶

7.1. Log Entry Schema

{
  "entryId": "alog_01HXYZ...",
  "agentId": "did:grantex:ag_01HXYZ123abc",
  "grantId": "grnt_01HXYZ...",
  "principalId": "user_abc123",
  "developerId": "org_yourcompany",
  "action": "payment.initiated",
  "status": "success",
  "metadata": {
    "amount": 420,
    "currency": "USD",
    "merchant": "Air India"
  },
  "timestamp": "2026-02-01T12:34:56.789Z",
  "hash": "sha256:abc123...",
  "prevHash": "sha256:xyz789..."
}

action values use the format resource.verb (e.g., payment.initiated, email.sent). status MUST be one of success, failure, or blocked.¶

7.2. Hash Chain

Each entry's hash is computed as a SHA-256 digest [RFC4648] over a canonical representation of the entry:¶

hash = SHA-256(canonical_json(entry_without_hash) || prevHash)

where canonical_json serializes all fields as a JSON object [RFC8259] with keys sorted alphabetically, and prevHash is the null string for the first entry in a chain. This construction makes any retrospective modification to a historical entry detectable, as it invalidates all subsequent hashes.¶

7.3. Audit Log Requirements

• Audit log entries MUST be append-only at the API level. No update or delete endpoints for audit entries are permitted.¶

• The Authorization Server MUST reject requests to modify or delete audit entries.¶

• The complete audit log for a Grant MUST remain accessible after the Grant is revoked, for a minimum retention period determined by the deployment's compliance requirements.¶

8.1. Delegation Token Claims

When Agent A spawns Agent B, B's Grant Token MUST carry delegation claims linking it to the original Principal's authorization:¶

{
  "sub": "user_abc123",
  "agt": "did:grantex:ag_B_456",
  "parentAgt": "did:grantex:ag_A_123",
  "parentGrnt": "grnt_parentXYZ",
  "scp": ["email:read"],
  "delegationDepth": 1
}

Additional delegation claims:¶

8.2. Delegation Rules

• Sub-agent scopes MUST be a strict subset of the parent Grant's scp array. Authorization Servers MUST reject delegation requests whose requested scopes are not fully contained in the parent token's scp claim.¶

• delegationDepth MUST be incremented by exactly 1 at each hop.¶

• Implementations MUST enforce a developer-configurable delegation depth limit. The RECOMMENDED default limit is 3. Implementations MUST enforce a hard cap of 10 regardless of developer configuration.¶

• The expiry of a delegated Grant Token MUST NOT exceed min(parent_token_exp, now + requested_expires_in).¶

8.3. Delegation Endpoint

POST /v1/grants/delegate
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "parentGrantToken": "eyJhbGciOiJSUzI1NiJ9...",
  "subAgentId": "ag_01HXYZ_sub",
  "scopes": ["email:read"],
  "expiresIn": "1h"
}

The Authorization Server MUST:¶

1. Validate that the parent Grant has not been revoked.¶

2. Reject with 400 if any requested scope is not present in the parent token's scp claim.¶

3. Reject with 400 if the resulting delegationDepth would exceed the configured limit.¶

4. Reject with 404 if subAgentId does not belong to the authenticated Developer.¶

5. Compute expiry as min(parent token exp, now + expiresIn).¶

Response 201 Created:¶

{
  "grantToken": "eyJhbGciOiJSUzI1NiJ9...",
  "grantId": "grnt_01HXYZ_sub",
  "scopes": ["email:read"],
  "expiresAt": "2026-02-01T01:00:00Z"
}

8.4. Cascade Revocation

Revoking a Grant via DELETE /v1/grants/:id MUST atomically revoke all descendant Grants — that is, all Grants whose parent_grant_id traces back to the revoked Grant at any depth. Authorization Servers SHOULD implement this as a single recursive database transaction to eliminate any window during which descendant tokens remain valid.¶

10.1. Purpose

The Policy Engine evaluates developer-defined rules against each authorization request before the consent UI is displayed. Policies enable developers to auto-approve routine low-risk requests and auto-deny requests that violate organizational constraints.¶

10.2. Effects

10.3. Condition Fields

10.4. Evaluation Order

Policy evaluation MUST follow this order:¶

1. auto_deny rules are evaluated first. The first matching deny rule wins and the request is rejected immediately.¶

2. auto_approve rules are evaluated next. The first matching allow rule causes the Grant Token to be issued.¶

3. If no rule matches, the consent UI is displayed to the Principal.¶

This ordering ensures that restrictive policies cannot be bypassed by a conflicting allow rule.¶

11.1. Purpose

The anomaly detection system monitors Agent behavior at runtime against each Agent's established activity baseline. It identifies behavioral deviations and surfaces them to Developers for review.¶

11.2. Non-Blocking Requirement

Anomaly detection MUST NOT block token issuance. Detection operates asynchronously as an advisory layer. Authorization Servers MUST NOT delay Grant Token responses pending anomaly analysis.¶

11.3. Anomaly Types

11.4. Severity Levels

Anomaly severity MUST be one of: low, medium, high, critical.¶

12.1. Algorithm Restrictions

All Grant Tokens MUST be signed with RS256 (RSASSA-PKCS1-v1_5 with SHA-256). Symmetric signing algorithms, including HS256, are NOT PERMITTED. All verifiers MUST explicitly reject tokens presenting alg: none or any symmetric algorithm, regardless of library defaults. This prevents algorithm confusion attacks as described in [RFC8725].¶

RSA key moduli MUST be at least 2048 bits. Authorization Servers generating or importing signing keys MUST enforce this minimum.¶

12.2. Token Replay Prevention

Every issued Grant Token carries a unique jti claim. Authorization Servers providing online verification MUST track issued jti values and reject any verification request presenting a jti that has already been used, for the full lifetime of the token.¶

12.3. CSRF and Redirect URI Security

The state parameter in the authorization request MUST be a cryptographically random, unpredictable value generated per-request. Developer callback handlers MUST validate the returned state value against the value sent in the original request.¶

Redirect URIs MUST be pre-registered by the Developer for each Agent. Authorization Servers MUST perform exact-match comparison of the redirectUri in each authorization request against the pre-registered set. Prefix matching and wildcard matching are NOT PERMITTED.¶

12.4. Scope Reduction for Delegation

Delegated Grant Tokens MUST carry a scope set that is a strict subset of the parent Grant's scope set. Authorization Servers MUST enforce this at token issuance time; it MUST NOT be enforced only at verification time.¶

12.5. Revocation Propagation

Authorization Servers MUST propagate grant revocation to all descendant grants atomically. The maximum allowable latency between a revocation request and the invalidation of all descendant tokens via the online verification endpoint is implementation-defined, but implementations SHOULD target sub-second propagation.¶

Implementations caching revocation state MUST NOT cache for longer than 300 seconds.¶

12.6. Consent UI Integrity

Consent UIs MUST display the agent name, developer name, all requested scopes with human-readable descriptions, token expiry, and a prominent deny/cancel action. This information MUST be sourced from the Authorization Server's registry, not from the authorization request itself, to prevent a malicious Developer from displaying misleading scope descriptions.¶

12.7. Audit Log Integrity

The hash-chain construction defined in Section 7 ensures that any modification to a historical audit entry is detectable. Implementations MUST store audit log entries in an append-only manner and MUST expose no API for modification or deletion of audit entries. Audit log export implementations SHOULD verify the hash chain before serving exports.¶

12.8. Enterprise Identity Security

SSO callback handlers MUST validate both the state (CSRF protection) and nonce (replay protection) parameters before establishing a session. ID tokens received in the SSO callback MUST be cryptographically verified against the identity provider's JWKS endpoint before any claims are trusted.¶

SCIM provisioning endpoints MUST authenticate via a credential (SCIM Bearer token) that is entirely separate from the Developer API key infrastructure. Compromise of a Developer API key MUST NOT grant access to SCIM provisioning endpoints, and vice versa.¶

13.1. JWT Claims Registration

This document requests registration of the following claims in the IANA "JSON Web Token Claims" registry established by [RFC7519]:¶

agt:

Claim Name: agt¶

Claim Description: Agent Decentralized Identifier¶

Change Controller: IETF¶

Specification Document: This document, Section 5¶

dev:

Claim Name: dev¶

Claim Description: Developer organization identifier¶

Change Controller: IETF¶

Specification Document: This document, Section 5¶

grnt:

Claim Name: grnt¶

Claim Description: Grant identifier for revocation lookup¶

Change Controller: IETF¶

Specification Document: This document, Section 5¶

scp:

Claim Name: scp¶

Claim Description: Array of granted authorization scope strings¶

Change Controller: IETF¶

Specification Document: This document, Section 5¶

parentAgt:

Claim Name: parentAgt¶

Claim Description: DID of the delegating parent Agent¶

Change Controller: IETF¶

Specification Document: This document, Section 8¶

parentGrnt:

Claim Name: parentGrnt¶

Claim Description: Grant identifier of the parent Grant¶

Change Controller: IETF¶

Specification Document: This document, Section 8¶

delegationDepth:

Claim Name: delegationDepth¶

Claim Description: Number of delegation hops from the root Grant¶

Change Controller: IETF¶

Specification Document: This document, Section 8¶

13.2. Well-Known URI Registration

No new Well-Known URIs are defined by this specification. Implementations use the existing /.well-known/jwks.json path established by [RFC8414].¶

14.1. Normative References

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC3986]

Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, <https://www.rfc-editor.org/rfc/rfc3986>.

[RFC4648]

Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, <https://www.rfc-editor.org/rfc/rfc4648>.

[RFC6749]

Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, <https://www.rfc-editor.org/rfc/rfc6749>.

[RFC6750]

Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, DOI 10.17487/RFC6750, October 2012, <https://www.rfc-editor.org/rfc/rfc6750>.

[RFC7517]

Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/RFC7517, May 2015, <https://www.rfc-editor.org/rfc/rfc7517>.

[RFC7518]

Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, DOI 10.17487/RFC7518, May 2015, <https://www.rfc-editor.org/rfc/rfc7518>.

[RFC7519]

Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, <https://www.rfc-editor.org/rfc/rfc7519>.

[RFC7636]

Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key for Code Exchange by OAuth Public Clients", RFC 7636, DOI 10.17487/RFC7636, September 2015, <https://www.rfc-editor.org/rfc/rfc7636>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

[RFC8259]

Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, <https://www.rfc-editor.org/rfc/rfc8259>.

[RFC8414]

Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, June 2018, <https://www.rfc-editor.org/rfc/rfc8414>.

14.2. Informative References

[DID-CORE]

W3C, "Decentralized Identifiers (DIDs) v1.0", 19 July 2022, <https://www.w3.org/TR/did-core/>.

[RFC7009]

Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, August 2013, <https://www.rfc-editor.org/rfc/rfc7009>.

[RFC7662]

Richer, J., Ed., "OAuth 2.0 Token Introspection", RFC 7662, DOI 10.17487/RFC7662, October 2015, <https://www.rfc-editor.org/rfc/rfc7662>.

[RFC8693]

Jones, M., Nadalin, A., Campbell, B., Ed., Bradley, J., and C. Mortimore, "OAuth 2.0 Token Exchange", RFC 8693, DOI 10.17487/RFC8693, January 2020, <https://www.rfc-editor.org/rfc/rfc8693>.

[RFC8725]

Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best Current Practices", BCP 225, RFC 8725, DOI 10.17487/RFC8725, February 2020, <https://www.rfc-editor.org/rfc/rfc8725>.

[ULID]

Feerasta, A., "Universally Unique Lexicographically Sortable Identifier", 2016, <https://github.com/ulid/spec>.