> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paddock.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API keys for your backend, session tokens for your frontend, and what each may do.

Every request carries one credential in the `Authorization` header:

```http theme={null}
Authorization: Bearer <API key or session token>
```

| Credential | Looks like | Used by | Grants |
| - | - | - | - |
| **API key** | `pdk_sk_` and 40 characters | Your backend, with a server SDK | Everything in its project |
| **Session token** | `pdk_st_...` | Your frontend, with the client SDK | Everything on one session, nothing else |

## 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.

```go Go theme={null}
client, err := paddock.NewClient(paddock.Options{APIKey: os.Getenv("PADDOCK_API_KEY")})
```

```python Python theme={null}
import os

client = Paddock(api_key=os.environ["PADDOCK_API_KEY"])
```

```ts TypeScript theme={null}
const paddock = new Paddock({ apiKey: process.env.PADDOCK_API_KEY });
```

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

```go Go theme={null}
tok, err := session.CreateToken(ctx, paddock.TokenCreate{TTL: time.Hour})
if err != nil {
	return err
}
fmt.Println(tok.Token, tok.ExpiresAt)
```

```python Python theme={null}
token = session.create_token(ttl=3600)
print(token.token, token.expires_at)
```

```ts TypeScript theme={null}
const { token, expiresAt } = await session.createToken({ ttl: 3600 });
```

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

| Answer | `details.reason` | Meaning |
| - | - | - |
| `401 unauthorized` | `missing` | No credential |
| `401 unauthorized` | `malformed` | Not a well-formed key or token |
| `401 unauthorized` | `unknown_key`, `revoked` | The API key does not exist, or was revoked |
| `401 unauthorized` | `bad_signature`, `expired` | The session token was altered, or has expired |
| `401 unauthorized` | `session_deleted` | The token's session or its agent was deleted |
| `403 forbidden` | | A session token used outside its session or its operations |

See [Errors](https://docs.paddock.build/platform/errors.md) 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](https://docs.paddock.build/guides/triggers.md#verify-signatures).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.