Authentication

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"

from wrenn import Capsule

capsule = Capsule(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"

from wrenn import Capsule

capsule = Capsule(base_url="https://your-self-hosted-instance.example.com/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

Status	Meaning
`401`	The API key is missing or invalid. Check that `WRENN_API_KEY` is set and the key hasn’t been deleted.
`403`	The 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

Get Started

Capsules

Code Interpreter

Advanced

Reference

Authentication

Get an API key

Authenticate with the SDK

Override the base URL

Authenticate REST requests directly

Error codes

​Get an API key

​Authenticate with the SDK

​Override the base URL

​Authenticate REST requests directly

​Error codes

Get an API key

Authenticate with the SDK

Override the base URL

Authenticate REST requests directly

Error codes