Auth Policies & Tokens

Containment Chamber can run open for Web3Signer-compatible migrations, or it can enforce runtime access control with policies and bearer tokens. Use policies when one signer serves multiple validator clients, when operators need different privileges, or when signing must be restricted to specific keys or operations.

The Auth API stores policies and tokens at runtime. Request and response schemas live in the interactive API Reference; this page explains the model and the common operating patterns.

Token Types

Token	Purpose	How to get it
Management token	Full management access. Used to create policies and client tokens.	containment-chamber operator generate-root-token
Client token	Limited access controlled by one or more policies.	Created through the Auth API by a management token holder
Setup token	One-time initialization token.	Logged on first boot while uninitialized
Registration token	One-time operator registration token.	Returned by operator init or operator rotate quorum

Bearer tokens are the primary transport:

Authorization: Bearer <token>

HTTP Basic is also accepted for validator clients that put credentials in the signer URL. The username is ignored and the password is treated as the token.

Policy Model

A policy is a named list of rules. Rules can allow or deny by:

• Scope: which route family the token can use.
• Key: which validator public keys the token can sign with.
• Operation: which Ethereum signing operation is allowed.

Example:

{
  "name": "validator-client-alpha",
  "rules": [
    {
      "effect": "allow",
      "scopes": ["sign", "public_keys"],
      "keys": ["0xabc123...", "0xdef456..."]
    },
    {
      "effect": "deny",
      "operations": ["VOLUNTARY_EXIT"]
    }
  ]
}

The common production pattern is:

1. Generate a management token after the chamber is unsealed.
2. Create one policy per validator client or tenant.
3. Create short-lived client tokens bound to those policies.
4. Configure validator clients with either Bearer tokens or Basic-auth URLs.

Common Policies

Validator client

Allows normal signing and public-key discovery for a bounded key set.

{
  "name": "validator-client-alpha",
  "rules": [
    {
      "effect": "allow",
      "scopes": ["sign", "public_keys"],
      "keys": ["0xabc123...", "0xdef456..."]
    },
    {
      "effect": "deny",
      "operations": ["VOLUNTARY_EXIT"]
    }
  ]
}

Monitoring

Allows status and key visibility without signing authority.

{
  "name": "monitoring",
  "rules": [
    {
      "effect": "allow",
      "scopes": ["public_keys", "list_keys", "chamber_status"]
    }
  ]
}

Exit operator

Allows a dedicated workflow to submit voluntary exits without granting broad operational access.

{
  "name": "exit-operator",
  "rules": [
    {
      "effect": "allow",
      "scopes": ["sign"],
      "operations": ["VOLUNTARY_EXIT"]
    }
  ]
}

Default Behavior

Auth is intentionally compatible with simple Web3Signer deployments.

Stored policies	unauthenticated_policy	Request without token
None	Not configured	Allowed
None	Configured	Checked against unauthenticated_policy
Present	Not configured	Rejected with 401
Present	Configured	Checked against unauthenticated_policy

Once policies exist, invalid or expired tokens are rejected. They are not silently downgraded to unauthenticated access.

For a single-tenant migration where validator clients do not send tokens, configure:

unauthenticated_policy:
  rules:
    - effect: allow
      scopes: [sign, public_keys]
    - effect: deny
      operations: [VOLUNTARY_EXIT]

Omit unauthenticated_policy when every caller must authenticate.

Key Visibility

The Web3Signer public-key endpoint only returns keys the caller can actually sign with. This prevents a validator client from accepting duties for keys it cannot sign.

GET /api/v1/eth2/publicKeys requires:

• public_keys scope.
• sign scope.
• Matching key rules, when a policy restricts keys.

The Chamber key-management listing endpoint is operational inventory. It is controlled by the chamber_keys_list scope and can show keys that are not signable by the caller.

CIDR-Bound Tokens

Client tokens can be bound to source CIDRs. Use this when validator clients have stable egress IPs and you want stolen tokens to fail outside that network path.

{
  "policies": ["validator-client-alpha"],
  "ttl_seconds": 86400,
  "allowed_cidrs": ["10.0.10.0/24"]
}

Management tokens are not CIDR-bound. Keep them in a secrets manager and rotate them like any root credential.

Scope Reference

The full endpoint-to-scope mapping is available in the API Reference. The most common scopes are:

Scope	Use
sign	Ethereum signing requests
public_keys	Web3Signer key discovery
chamber_status	Seal state and operational status
chamber_seal	Emergency seal
chamber_rotate	KMS, operator, and mode rotation
chamber_keys_list	Chamber key inventory
chamber_keys_generate	DynamoDB key generation
chamber_keys_import	Runtime key import
auth_policies_manage	Policy administration
auth_tokens_manage	Token administration

Tip

Keep policy documents small and composable. A validator-client policy, a monitoring policy, and a separate exit policy are easier to review than one large policy that mixes every role.