Skip to main content
Every request carries one credential in the Authorization header:

API keys

Create API keys in the console’s API Keys page. A key is shown once, when it is created; paddock stores only a hash of it. Revoking a key takes effect on its next request. Keep keys on your backend. The server SDKs read PADDOCK_API_KEY from the environment when you pass none, and PADDOCK_BASE_URL for the API’s base URL. When neither the option nor the environment gives a key, they read apiKey and baseUrl from the credentials file that paddock auth login writes, $XDG_CONFIG_HOME/paddock/credentials or ~/.config/paddock/credentials. The file’s key and base URL are used only together: a key from the option or the environment goes to PADDOCK_BASE_URL or the default, never to the file’s base URL, and the file’s key is never sent to another base URL; construction fails instead. The base URL defaults to https://api.paddock.build/v1. A file that is needed but unreadable fails construction with its path; run paddock auth login to replace it or paddock auth logout to remove it.
A key belongs to one project, and every request is scoped to it: a resource of another project answers 404, so a key cannot learn that it exists.

Session tokens

A session token hands one session to a browser. Your backend creates it for a session with a lifetime in seconds, from 60 to 86,400 (24 hours):
On its own session, a token can do everything the server SDK can:
  • read the session, its events, its turns, and its stream;
  • send messages and stop turns;
  • create another token for the same session, which expires no later than itself;
  • delete the session.
Anything else, such as listing sessions or reading the agent, is 403 forbidden. Nothing is stored for a token, and tokens are not revoked one by one: a token works until it expires, or until its session or agent is deleted. The client SDK sends the token only in the Authorization header, never in a URL. Mint tokens only for sessions the signed-in user may see. paddock does not know your users; that check is your backend’s.

Failures

See Errors for the error body.

Webhook senders

The trigger webhook endpoint, https://trigger.paddock.build/{id}, takes no credential: its URL is unguessable, and a trigger can require an HMAC-SHA256 signature with its own secret. See Triggers.