Skip to main content
Every request to the Wrenn API must include a valid API key. You can provide it through an environment variable — which the SDK picks up automatically — or pass it explicitly when constructing a Capsule. API keys are scoped to your team and have the prefix wrn_.

​
Get an API key

Open the Wrenn dashboard, navigate to Settings → API Keys, and create a new key. The plaintext key is shown only once at creation time — copy it immediately and store it somewhere safe.
Never commit API keys to source control. Use environment variables, a secrets manager, or a .env file excluded from version control.

​
Authenticate with the SDK

You have two options for providing credentials to the SDK. 
export WRENN_API_KEY="wrn_your_api_key_here"
When WRENN_API_KEY is set, you never need to pass api_key= explicitly: 
from wrenn import Capsule

# Reads WRENN_API_KEY from the environment
with Capsule(template="minimal", wait=True) as capsule:
    result = capsule.commands.run("echo hello")
    print(result.stdout)

​
Override the base URL

By default the SDK points to https://app.wrenn.dev/api. You can override this with the WRENN_BASE_URL environment variable or the base_url= argument: 
export WRENN_BASE_URL="https://app.wrenn.dev/api"

​
Authenticate REST requests directly

If you call the API directly rather than through the SDK, include your key in the X-API-Key header: 
curl https://app.wrenn.dev/api/v1/capsules \
  -H "X-API-Key: wrn_your_api_key_here"

​
Error codes

StatusMeaning
401The API key is missing or invalid. Check that WRENN_API_KEY is set and the key hasn’t been deleted.
403The key is valid but not authorized to access this resource.
The SDK surfaces these as typed exceptions: 
from wrenn import WrennAuthenticationError, WrennForbiddenError

try:
    capsule = Capsule(api_key="wrn_bad_key")
except WrennAuthenticationError as e:
    print(e.message)     # "unauthorized"
    print(e.status_code) # 401