⚡ Getting Started

Quick Start

From zero to a working secret vault in under 5 minutes.

Prerequisites

You need a free Agent Secret Store account. Sign up at agentsecretstore.com/signup — no credit card required. Create an agent from the dashboard to get an agent key.

1
Install the SDK
Choose the SDK for your agent's runtime:
Python (async-native)
Shell
pip install agentsecretstore
JavaScript / TypeScript
Shell
npm install @agentsecretstore/sdk
Prefer HTTP? Skip the SDK and use the REST API directly. MCP users: see the MCP server guide.
2
Set your agent key
Copy your agent key from the dashboard and export it as an environment variable:
Shell
export ASS_AGENT_KEY="ass_your_key_here"
Keep this key secret
Your agent key (ASS_AGENT_KEY) can request scoped tokens for the agent's allowed namespaces. Never commit it to source control or embed it in a container image. Store it in your CI/CD secret manager (GitHub Actions Secrets, AWS Secrets Manager, etc.) and inject it at runtime.

Store your first secret

Store a secret using the Python SDK or raw HTTP. Raw HTTP uses the agent key only to request a scoped write token first:

Python

store_secret.py

import asyncio
import os
from agentsecretstore import AgentVault

async def main():
    async with AgentVault(agent_key=os.environ["ASS_AGENT_KEY"]) as vault:
        await vault.set_secret(
            path="production/gemini/GEMINI_API_KEY",
            value="gemini-api-key-example",
            secret_type="api_key",
            access_tier="standard",
            metadata={"team": "ml", "env": "production"},
        )
    print("Secret stored!")

asyncio.run(main())

curl

Shell

ASS_SCOPED_TOKEN=$(curl -s -X POST https://api.agentsecretstore.com/v1/tokens \
  -H "Authorization: Bearer $ASS_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scopes":["secrets:write:production/gemini/GEMINI_API_KEY"],"ttl":"1h"}' | jq -r .token)

curl -X PUT https://api.agentsecretstore.com/v1/secrets/production/gemini/GEMINI_API_KEY \
  -H "Authorization: Bearer $ASS_SCOPED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "gemini-api-key-example",
    "secret_type": "api_key",
    "access_tier": "standard",
    "metadata": {"team": "ml", "env": "production"}
  }'

Secret paths use the format namespace/key. The access_tier controls approval requirements — see approval workflows.

Retrieve the secret

Read the secret back. The SDK exchanges your agent key for the narrow scoped token each operation needs:

Python

retrieve.py

import asyncio
import os
from agentsecretstore import AgentVault

async def main():
    async with AgentVault(agent_key=os.environ["ASS_AGENT_KEY"]) as vault:
        value = await vault.get_secret("production/gemini/GEMINI_API_KEY")
        metadata = await vault.get_secret_with_metadata("production/gemini/GEMINI_API_KEY")

    print(value)                 # "gemini-api-key-example"
    print(metadata.version)      # 1
    print(metadata.secret_type)  # "api_key"
    print(metadata.access_tier)  # "standard"

asyncio.run(main())

JavaScript / TypeScript

retrieve.ts

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

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

const value = await vault.getSecret('production/gemini/GEMINI_API_KEY');
const metadata = await vault.getSecretWithMetadata('production/gemini/GEMINI_API_KEY');
console.log(value);                // "gemini-api-key-example"
console.log(metadata.version);     // 1
console.log(metadata.secret_type); // "api_key"

Issue scoped tokens for your agents

For handoffs to short-lived tasks or non-SDK clients, issue a scoped token that limits access to exactly the secrets they need:

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:
        # Request a scoped token that only allows reading Gemini keys
        try:
            response = await vault.request_token(
                ["secrets:read:production/gemini/*"],
                ttl="1h",
            )
        except ApprovalRequiredError as exc:
            print(f"Approval required: {exc.approval_id}")
            return

        # Share this JWT with a task that calls the REST API directly.
        print(f"Token: {response.token}")
        print(f"Expires: {response.expires_at}")

asyncio.run(main())

Security principle

Give each agent the narrowest possible scope and the shortest TTL that still works. A token scoped to secrets:read:production/gemini/* can read keys directly under production/gemini, but not Stripe keys, Slack tokens, or deeper nested namespaces.

Authentication

Agent Secret Store uses two types of credentials:

Agent Key

Prefix: ass_…

Long-lived credential for one agent. It can request scoped tokens within that agent’s namespace and scope limits.

Env: ASS_AGENT_KEY

Scoped Token

Prefix: JWT…

Short-lived bearer token with explicit scopes, TTL, optional max uses, and optional IP allowlist.

Env: Provided at runtime

Next steps

Scoped Tokens →

Deep dive into token scopes, TTLs, and single-use tokens.

Approval Workflows →

Set up multi-approver gates for sensitive credentials.

Python SDK Reference →

Every method, parameter, and error type documented.

import asyncio import os from agentsecretstore import AgentVault async def main(): async with AgentVault(agent_key=os.environ["ASS_AGENT_KEY"]) as vault: await vault.set_secret( path="production/gemini/GEMINI_API_KEY", value="gemini-api-key-example", secret_type="api_key", access_tier="standard", metadata={"team": "ml", "env": "production"}, ) print("Secret stored!") asyncio.run(main())

ASS_SCOPED_TOKEN=$(curl -s -X POST https://api.agentsecretstore.com/v1/tokens \ -H "Authorization: Bearer $ASS_AGENT_KEY" \ -H "Content-Type: application/json" \ -d '{"scopes":["secrets:write:production/gemini/GEMINI_API_KEY"],"ttl":"1h"}' | jq -r .token) curl -X PUT https://api.agentsecretstore.com/v1/secrets/production/gemini/GEMINI_API_KEY \ -H "Authorization: Bearer $ASS_SCOPED_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "value": "gemini-api-key-example", "secret_type": "api_key", "access_tier": "standard", "metadata": {"team": "ml", "env": "production"} }'

import asyncio import os from agentsecretstore import AgentVault async def main(): async with AgentVault(agent_key=os.environ["ASS_AGENT_KEY"]) as vault: value = await vault.get_secret("production/gemini/GEMINI_API_KEY") metadata = await vault.get_secret_with_metadata("production/gemini/GEMINI_API_KEY") print(value) # "gemini-api-key-example" print(metadata.version) # 1 print(metadata.secret_type) # "api_key" print(metadata.access_tier) # "standard" asyncio.run(main())

import { AgentVault } from '@agentsecretstore/sdk'; const vault = new AgentVault({ agentKey: process.env.ASS_AGENT_KEY!, }); const value = await vault.getSecret('production/gemini/GEMINI_API_KEY'); const metadata = await vault.getSecretWithMetadata('production/gemini/GEMINI_API_KEY'); console.log(value); // "gemini-api-key-example" console.log(metadata.version); // 1 console.log(metadata.secret_type); // "api_key"

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: # Request a scoped token that only allows reading Gemini keys try: response = await vault.request_token( ["secrets:read:production/gemini/*"], ttl="1h", ) except ApprovalRequiredError as exc: print(f"Approval required: {exc.approval_id}") return # Share this JWT with a task that calls the REST API directly. print(f"Token: {response.token}") print(f"Expires: {response.expires_at}") asyncio.run(main())

Authentication

Agent Secret Store uses two types of credentials:

Agent Key

Prefix: ass_…

Long-lived credential for one agent. It can request scoped tokens within that agent’s namespace and scope limits.

Env: ASS_AGENT_KEY

Scoped Token

Prefix: JWT…

Short-lived bearer token with explicit scopes, TTL, optional max uses, and optional IP allowlist.

Env: Provided at runtime

Install the SDK

Set your agent key

Store your first secret

Retrieve the secret

Issue scoped tokens for your agents

Authentication

Next steps

Scoped Tokens →

Approval Workflows →

Python SDK Reference →

Install the SDK

Set your agent key

Store your first secret

Retrieve the secret

Issue scoped tokens for your agents

Authentication

Next steps

Scoped Tokens →

Approval Workflows →

Python SDK Reference →