🔑 Concepts

Scoped Tokens

Short-lived, least-privilege credentials for agent tasks and direct REST calls.

Why scoped tokens?

Your agent key (ASS_AGENT_KEY) can request scoped tokens within the agent's configured namespace and scope limits. Passing a narrower token to a task reduces blast radius if that task is compromised.

Scoped tokens solve this with the principle of least privilege: each agent gets a token that expires, is limited to specific actions, and only covers the specific secrets it needs.

TOKEN LIFECYCLE

Orchestrator requests token— Using agent key + scopes + TTL

↓

Vault validates + issues token— Approval check if tier = sensitive/critical

↓

Token passed to agent— Via env var, message queue, or API response

↓

Agent reads secret with token— Vault enforces scope + TTL + IP allowlist

↓

Token expires / burns— After TTL or max_uses reached — no revocation needed

Scope format

Scopes use a three-part format:

secretsResource type (always "secrets")

actionread | write

namespace/key_patternPath with optional glob (*)

Examples:

Shell

# Read any key in production/gemini/*
secrets:read:production/gemini/*

# Read a specific single key
secrets:read:production/stripe/WEBHOOK_SECRET

# Write secrets in a staging namespace
secrets:write:staging/*

# List namespaces visible to the agent
secrets:read:*

Requesting a token

Python

request_token.py

import asyncio
import os
from agentsecretstore import AgentVault
from agentsecretstore import ApprovalRequiredError

async def main():
    async with AgentVault(agent_key=os.environ["ASS_AGENT_KEY"]) as vault:
        # Minimal scope for a read-only inference agent
        try:
            token = await vault.request_token(
                ["secrets:read:production/gemini/*"],
                ttl="1h",
            )
        except ApprovalRequiredError as exc:
            print(f"Approval required: {exc.approval_id}")
            return

        print(token.token)      # JWT bearer token
        print(token.expires_at) # 2026-06-02T11:30:00Z

asyncio.run(main())

TypeScript

requestToken.ts

import { AgentVault } from '@agentsecretstore/sdk';

const vault = new AgentVault({
  agentKey: process.env.ASS_AGENT_KEY!,
});

const token = await vault.requestToken({
  scopes: ['secrets:read:production/gemini/*'],
  ttl: '1h',
  ipAllowlist: ['10.0.1.50'],
  maxUses: 10,
});

console.log(token.token);      // JWT bearer token
console.log(token.expires_at); // "2026-06-02T11:30:00Z"

curl

Shell

curl -X POST https://api.agentsecretstore.com/v1/tokens \
  -H "Authorization: Bearer $ASS_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": ["secrets:read:production/gemini/*"],
    "ttl": "1h",
    "max_uses": 10,
    "ip_allowlist": ["10.0.1.50"]
  }'

Token parameters

Parameter	Type	Default	Description
scopes	string[]	required	Permission scope strings (see format above)
ttl	string	1h	Token lifetime: 5m to 24h using s, m, h, or d suffixes
max_uses	int \| null	null	Maximum successful request count; null = unlimited within TTL
ip_allowlist	string[] \| null	null	Optional IPv4, IPv6, or CIDR allowlist; null = any IP

Single-use tokens

Set max_uses=1 to create a burn-after-reading token. After the agent retrieves the secret once, the token is invalidated server-side.

Shell

curl -X POST https://api.agentsecretstore.com/v1/tokens \
  -H "Authorization: Bearer $ASS_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": ["secrets:read:production/stripe/STRIPE_SECRET_KEY"],
    "ttl": "5m",
    "max_uses": 1
  }'

Use case: payment processing

Single-use tokens are ideal for one-time operations like payment processing, where you want to ensure the credential can only be used once per task invocation.

Using a scoped token

Use a scoped token as a bearer token on REST calls. The SDKs normally use an agent key and request scoped tokens automatically for each operation.

agent_usage.sh

curl https://api.agentsecretstore.com/v1/secrets/production/gemini/GEMINI_API_KEY \
  -H "Authorization: Bearer $ASS_SCOPED_TOKEN"

# This returns 403 SCOPE_DENIED if the token does not include
# secrets:read:production/gemini/GEMINI_API_KEY or a matching wildcard scope.

Scope violations raise errors

Attempting to read a path outside the token's scope raises ScopeError (HTTP 403). Design your agents to catch this and request a new token with appropriate scope rather than silently failing.

IP allowlisting

Tokens can be restricted to specific source IP addresses. If a request arrives from an IP not in the allowlist, the vault returns HTTP 403 regardless of token validity. This provides defense in depth — even a stolen token is useless from the wrong host.

Both IPv4 and IPv6 are supported. CIDR notation (e.g. 10.0.0.0/24) is accepted for specifying subnets.

Approval Workflows →

Set up approval gates for sensitive token requests.

Python SDK →

Complete reference for request_token() and all parameters.

🔑 Concepts

Scoped Tokens

Short-lived, least-privilege credentials for agent tasks and direct REST calls.

Why scoped tokens?

Scoped tokens solve this with the principle of least privilege: each agent gets a token that expires, is limited to specific actions, and only covers the specific secrets it needs.

TOKEN LIFECYCLE

Orchestrator requests token— Using agent key + scopes + TTL

↓

Vault validates + issues token— Approval check if tier = sensitive/critical

↓

Token passed to agent— Via env var, message queue, or API response

↓

Agent reads secret with token— Vault enforces scope + TTL + IP allowlist

↓

Token expires / burns— After TTL or max_uses reached — no revocation needed

Scope format

Scopes use a three-part format:

secretsResource type (always "secrets")

actionread | write

namespace/key_patternPath with optional glob (*)

Examples:

Shell

# Read any key in production/gemini/*
secrets:read:production/gemini/*

# Read a specific single key
secrets:read:production/stripe/WEBHOOK_SECRET

# Write secrets in a staging namespace
secrets:write:staging/*

# List namespaces visible to the agent
secrets:read:*

Requesting a token

Python

request_token.py

import asyncio
import os
from agentsecretstore import AgentVault
from agentsecretstore import ApprovalRequiredError

async def main():
    async with AgentVault(agent_key=os.environ["ASS_AGENT_KEY"]) as vault:
        # Minimal scope for a read-only inference agent
        try:
            token = await vault.request_token(
                ["secrets:read:production/gemini/*"],
                ttl="1h",
            )
        except ApprovalRequiredError as exc:
            print(f"Approval required: {exc.approval_id}")
            return

        print(token.token)      # JWT bearer token
        print(token.expires_at) # 2026-06-02T11:30:00Z

asyncio.run(main())

TypeScript

requestToken.ts

import { AgentVault } from '@agentsecretstore/sdk';

const vault = new AgentVault({
  agentKey: process.env.ASS_AGENT_KEY!,
});

const token = await vault.requestToken({
  scopes: ['secrets:read:production/gemini/*'],
  ttl: '1h',
  ipAllowlist: ['10.0.1.50'],
  maxUses: 10,
});

console.log(token.token);      // JWT bearer token
console.log(token.expires_at); // "2026-06-02T11:30:00Z"

curl

Shell

curl -X POST https://api.agentsecretstore.com/v1/tokens \
  -H "Authorization: Bearer $ASS_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": ["secrets:read:production/gemini/*"],
    "ttl": "1h",
    "max_uses": 10,
    "ip_allowlist": ["10.0.1.50"]
  }'

Token parameters

Parameter	Type	Default	Description
scopes	string[]	required	Permission scope strings (see format above)
ttl	string	1h	Token lifetime: 5m to 24h using s, m, h, or d suffixes
max_uses	int \| null	null	Maximum successful request count; null = unlimited within TTL
ip_allowlist	string[] \| null	null	Optional IPv4, IPv6, or CIDR allowlist; null = any IP

Single-use tokens

Set max_uses=1 to create a burn-after-reading token. After the agent retrieves the secret once, the token is invalidated server-side.

Shell

curl -X POST https://api.agentsecretstore.com/v1/tokens \
  -H "Authorization: Bearer $ASS_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": ["secrets:read:production/stripe/STRIPE_SECRET_KEY"],
    "ttl": "5m",
    "max_uses": 1
  }'

Use case: payment processing

Single-use tokens are ideal for one-time operations like payment processing, where you want to ensure the credential can only be used once per task invocation.

Using a scoped token

Use a scoped token as a bearer token on REST calls. The SDKs normally use an agent key and request scoped tokens automatically for each operation.

agent_usage.sh

curl https://api.agentsecretstore.com/v1/secrets/production/gemini/GEMINI_API_KEY \
  -H "Authorization: Bearer $ASS_SCOPED_TOKEN"

# This returns 403 SCOPE_DENIED if the token does not include
# secrets:read:production/gemini/GEMINI_API_KEY or a matching wildcard scope.

Scope violations raise errors

Attempting to read a path outside the token's scope raises ScopeError (HTTP 403). Design your agents to catch this and request a new token with appropriate scope rather than silently failing.

IP allowlisting

Both IPv4 and IPv6 are supported. CIDR notation (e.g. 10.0.0.0/24) is accepted for specifying subnets.

Approval Workflows →

Set up approval gates for sensitive token requests.

Python SDK →

Complete reference for request_token() and all parameters.