Delegation Tokens

For: Application developers and platform engineers integrating with Axemere Gateway.

Developer Integration | Delegation Tokens | Merkle Proof Verification

A delegation token grants a downstream caller scoped, time-limited authority to perform actions through Axemere Gateway. Tokens are Ed25519-signed JSON documents; the gateway verifies the signature and scope before allowing the request to proceed. No token, no action.

Table of Contents

• When to Use Delegation Tokens
• Token Structure
  • Scope Fields
  • Budget Fields
  • Attribution Fields
• Trust Model
• Creating a Token
  • Go SDK
  • Raw JSON (any language)
• Using a Token in a Request
• Gateway Verification Steps
• Policy DSL Fields
• Delegation Chains
• Security Considerations
• Environment Variables
• Troubleshooting
• See Also

When to Use Delegation Tokens

Use delegation tokens when a system component needs to call an AI provider on behalf of a user or another service, but should not have full platform authority. Common patterns:

Delegation tokens are optional. Requests without tokens are evaluated against policy with no delegation context. See Developer Integration for the base request format.

Token Structure

The wire schema is "mvgc.delegation.v2". All fields use JCS (RFC 8785) canonical serialization before signing.

{
  "schema": "mvgc.delegation.v2",
  "delegation_id": "01955f3e-1234-7abc-8def-000000000001",
  "org_id": "01955f3e-0000-7abc-8def-000000000001",
  "workload_id": "01955f3e-0000-7abc-8def-000000000002",
  "principal_id": "user-abc",
  "policy_bundle_id": "01955f3e-0000-7abc-8def-000000000003",
  "issued_at": "2026-03-12T10:00:00Z",
  "expires_at": "2026-03-12T11:00:00Z",
  "budget": {
    "model_tokens_max": 50000,
    "usd_max": "5.00"
  },
  "scope": {
    "actions_allow": ["ai.infer"],
    "targets_allow": ["api.openai.com"],
    "methods_allow": ["POST"],
    "resource_patterns_allow": ["^/v1/chat/.*"]
  },
  "attribution": {
    "defaults": {
      "customer_id": "cust-42",
      "project_id": "proj-123",
      "labels": { "env": "prod" }
    },
    "allow_overrides": ["project_id", "labels"]
  },
  "jti": "unique-per-token-nonce",
  "sig": { "alg": "ed25519", "kid": "kid_cp_del_1", "sig": "<base64url>" }
}

Scope Fields

All scope fields are lists of permitted values. An empty list or omitted field means no restriction for that dimension.

The gateway intersects the token's scope with policy. A request must satisfy both.

Budget Fields

Budgets are enforced per-token in addition to workload-level budgets. When either cap is reached, subsequent requests using the token are denied.

Attribution Fields

attribution.defaults provides fallback values for fields not set on the request. attribution.allow_overrides lists which fields the caller may override per-request.

"attribution": {
  "defaults": {
    "customer_id": "cust-42",
    "project_id": "proj-123",
    "account_id": "acct-7",
    "labels": { "team": "payments", "env": "prod" }
  },
  "allow_overrides": ["project_id", "labels"]
}

A field in allow_overrides may be set by the caller in the request body. A field not in the list is locked to the token default; the caller cannot change it.

Trust Model

The token issuer holds the private signing key. The gateway holds only the public verification key. The gateway never generates tokens; it only verifies them.

Trust boundaries:

• The issuer is responsible for setting correct scope, budget, and expiry
• The gateway enforces that the token is valid and matches the request
• Policy may further restrict what a valid token can do

Creating a Token

Go SDK

import (
    "github.com/axemere/gateway/delegation"
    "github.com/axemere/gateway/signing"
    "time"
)

signer := signing.NewSigner(privKey)

tokenBytes, err := delegation.CreateToken(signer, delegation.DelegationClaims{
    IssuedBy:    "my-backend-service",
    OrgID:       "01955f3e-0000-7abc-8def-000000000001",
    WorkloadID:  "01955f3e-0000-7abc-8def-000000000002",
    PrincipalID: "user-abc",                             // optional
    TTL:         time.Hour,
    Scope: delegation.Scope{
        ActionsAllow:          []string{"ai.infer"},
        TargetsAllow:          []string{"api.openai.com"},
        MethodsAllow:          []string{"POST"},
        ResourcePatternsAllow: []string{"^/v1/chat/.*"},
    },
    Budget: delegation.Budget{
        USDMax:        "5.00",
        ModelTokensMax: 50000,
    },
    Attribution: delegation.TokenAttribution{
        Defaults: map[string]string{
            "project_id": "proj-123",
            "customer_id": "cust-42",
        },
        AllowOverrides: []string{"project_id"},
    },
})
if err != nil {
    return fmt.Errorf("create delegation token: %w", err)
}

// tokenBytes is the base64-encoded signed token for inclusion in requests

Raw JSON (any language)

1. Build the token JSON document matching the schema above.
2. Serialize to canonical JSON using JCS (RFC 8785): deterministic key order, no insignificant whitespace.
3. Compute SHA-256(canonical_bytes).
4. Sign the hash with Ed25519 using your delegation signing key.
5. Base64url-encode the signature and embed it in the sig envelope.
6. Base64-encode the entire signed JSON for transport.

Using a Token in a Request

Include the token in the Action Request body:

{
  "schema": "mvgc.action_request.v2",
  "request_id": "01955f3e-aaaa-7abc-8def-000000000099",
  "org_id": "01955f3e-0000-7abc-8def-000000000001",
  "caller_id": "my-backend-service",
  "delegation_id": "01955f3e-1234-7abc-8def-000000000001",
  "delegation_token": "<base64-encoded signed token>",
  "action": {
    "type": "ai.infer",
    "target": "https://api.openai.com",
    "method": "POST",
    "path": "/v1/chat/completions"
  }
}

Or via HTTP headers when using transparent proxy mode:

X-MVGC-Delegation-ID: 01955f3e-1234-7abc-8def-000000000001
X-MVGC-Delegation-Token: <base64-encoded signed token>

Gateway Verification Steps

When a token is present, the gateway performs these checks in order before policy evaluation:

1. Signature: Verified against MVGC_DELEGATION_VERIFY_KEY using kid from the token's sig envelope.
2. Expiry: expires_at must be in the future; issued_at must not be more than 5 minutes in the future.
3. Org match: Token org_id must match the gateway's configured org.
4. Chain depth: The delegation chain depth must be ≤ 3 (see Delegation Chains).
5. Scope intersection: At policy evaluation time, the request action and target are checked against the token's scope fields.

Policy DSL Fields

After a token passes verification, these fields are available in policy rules:

Use the in operator to check membership in list fields:

rules:
  - id: allow.delegation.infer.only
    conditions:
      all:
        - field: context.delegation.actions_allow
          operator: in
          value: "ai.infer"
    effect: allow

Delegation Chains

A token may itself authorize a downstream actor to further delegate. The depth field tracks how many times authority has been re-delegated:

• Maximum chain depth is 3.
• Each delegation hop increments the depth counter.
• A token with depth=3 cannot be re-delegated; any attempt results in a 403 delegation_depth_exceeded.
• Depth is enforced at verification time; it does not affect the token schema.

Security Considerations

Token TTL guidance: Use the shortest TTL that does not cause operational friction. For user-session-scoped tokens, 1 hour is typical. For short-lived agent tasks, 5–15 minutes is preferred.

Environment Variables

The signing and verification keys are separate: the issuer system holds the private key; the gateway holds only the public key.

Troubleshooting

See Also

• Developer Integration Guide: base request format and ingress modes
• Admin API Reference: workload and credential management
• Glossary: delegation_token
• Glossary: principal_id