Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.alterauth.com/llms.txt

Use this file to discover all available pages before exploring further.

A managed secret is a backend-only credential — an API key, service-account token, or Stripe key — that the developer stores in Alter instead of an env var or secret manager. Same vault as OAuth, same vault.request() surface, no end-user OAuth flow. For credentials that end users authorize themselves (Gmail, Slack, GitHub on their behalf), use OAuth grants instead.

​
When to use Managed Secrets

  • The credential already exists (generated in the provider’s console).
  • The credential is per-service or per-tenant, not per-end-user.
  • Centralized credential management is preferable to scattering API keys across env vars.

​
How it differs from OAuth

OAuth grantsManaged secrets
Who provides the credentialEnd user authorizes via OAuthOperator provisions in the developer portal
Where grant_id comes fromOAuth flow resultDeveloper portal at provisioning time
RefreshAutomaticNot needed (operator rotates when the underlying credential rotates)
End-user revocationIn Walletn/a — operator-controlled only
PrincipalUser (almost always)User, Group, System, or Agent

​
How it works

1

Store

Add the credential in the developer portal under Managed Secrets. Pick a credential type (Bearer Token, API Key, Basic Auth, AWS SigV4) and bind it to a principal.
2

Get a grant_id

The portal returns a grant_id (UUID). Copy it into application config.
3

Use

Call vault.request(..., grant_id=...) — same as OAuth grants.
4

Rotate

When the underlying credential rotates, update the stored value in the portal. The grant_id stays stable.

​
Quick example

from alter_sdk import App, HttpMethod

vault = App(api_key=ALTER_API_KEY)

response = await vault.request(
    HttpMethod.POST,
    "https://api.openai.com/v1/chat/completions",
    grant_id=OPENAI_GRANT_ID,
    json={"model": "gpt-4", "messages": [{"role": "user", "content": "Hello"}]},
)

​
Credential types

TypeHeader injected
Bearer TokenAuthorization: Bearer <token>
API KeyCustom header (e.g., X-API-Key: <key>)
Basic AuthAuthorization: Basic <base64(user:pass)>
AWS SigV4AWS Signature Version 4 (computed automatically per request)

​
Per-provider templates and “Custom”

Alter ships pre-configured templates for 30+ services (see the Managed Secret Providers section in the sidebar). For anything not in the catalog, pick Custom when adding a managed secret in the portal — custom header names, custom injection formats (Token {token}, Key {token}), and multi-header / query-parameter injection are all configurable.

​
What’s included

  • Write-only storage. Stored values can never be read back, only used via vault.request().
  • Same security as OAuth. AES-256-GCM encryption, policy enforcement, audit logging.
  • Multi-principal binding. A single secret can be issued as separate grants to different users, groups, agents, or system.
  • Time-bounded grants. Set TTL via grant_policy when issuing.

​
See also

Issuing grants

Operator surface for binding stored secrets to principals.

Using grants

Developer surface — vault.request, proxy_request, boto3_client.

Provider directory

30+ pre-configured templates.

OAuth grants

For end-user-authorized credentials.