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 readPADDOCK_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.
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):- 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.
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.