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

# Authentication

> Authenticate with the Tiny Talk API using API keys to send messages programmatically.

The Tiny Talk API lets you send messages to your agent programmatically from any backend, script, or integration. The base URL for all requests is:

```
https://api.tinytalk.ai/v1
```

## Public vs. private agents

Every agent in Tiny Talk is **public by default**. A public agent accepts messages from anyone without authentication — this is how the embedded chat widget works on your website.

When you make an agent **private**, every request must include a valid API key. Private agents reject unauthenticated requests with a `401 Unauthorized` response.

| Agent visibility | API key required? | Use case                                                         |
| ---------------- | ----------------- | ---------------------------------------------------------------- |
| **Public**       | No                | Website chat widget, open-access assistants                      |
| **Private**      | Yes               | Server-to-server integrations, internal tools, controlled access |

<Info>
  You can change an agent's visibility in the dashboard under **Settings → General**.
</Info>

## API key

To authenticate API requests, include your API key in the `api-key` header:

```bash theme={null}
api-key: tiny_sk_your_key_here
```

### Getting your API key

<Steps>
  <Step title="Open the dashboard">
    Go to [dashboard.tinytalk.ai](https://dashboard.tinytalk.ai) and select your agent.
  </Step>

  <Step title="Navigate to Integrations">
    Click **Integrations** in the sidebar, then scroll find **Hub → Tiny Talk** section.
  </Step>

  <Step title="Create an API key">
    Click **Create API Key**. Your key is shown once — copy it and store it securely.
  </Step>
</Steps>

<Warning>
  Keep your API key secret. Do not expose it in client-side code, public repositories, or browser requests. Use it only from your server or backend.
</Warning>

### API key benefits

Requests authenticated with a valid API key:

* Can access **private** agents
* **Bypass rate limiting** — no per-user message throttling
* Are identified as trusted server-to-server traffic

## Rate limiting

Unauthenticated requests (public agents without an API key) are rate-limited per user based on the agent's [rate limit settings](/features/agent-settings#rate-limiting). When the limit is exceeded, the API returns a `429` status code with rate limit headers:

| Header                  | Description                              |
| ----------------------- | ---------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed in the window   |
| `X-RateLimit-Remaining` | Requests remaining in the current window |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets    |
| `Retry-After`           | Seconds to wait before retrying          |

## Error format

All errors return a JSON response with a status code and message:

```json theme={null}
{
  "code": 400,
  "message": "Description of what went wrong"
}
```

| Code  | Meaning                                                       |
| ----- | ------------------------------------------------------------- |
| `200` | Success                                                       |
| `400` | Bad request — invalid or missing parameters                   |
| `401` | Unauthorized — invalid or missing API key for a private agent |
| `403` | Forbidden — plan limit exceeded (messages or model access)    |
| `429` | Rate limited — too many requests                              |
| `500` | Internal server error                                         |