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

# Authentication

> How to authenticate API requests with your OneInbox API key.

OneInbox has two kinds of keys. Which one you use depends on where your code runs — that distinction is the whole reason both exist.

| Key                 | Starts with | Runs where             | Can do                                            |
| ------------------- | ----------- | ---------------------- | ------------------------------------------------- |
| **API key**         | `oi_sk_`    | Your server (backend)  | Everything — create agents, make calls, read data |
| **Publishable key** | `oi_pk_`    | The browser (frontend) | Only start a call — nothing else                  |

Use your **API key** for everything in this section. For the **publishable key**, see [Web SDK](/concepts/web-sdk) — it's created differently and used only to let website visitors start a call directly from your site.

***

## API key — full access, server only

Your API key is the master credential for your OneInbox account. Anything this documentation shows you — creating agents, making calls, managing tools, reading call records, billing, everything — goes through this key.

* **Format**: `oi_sk_...`
* **Lives**: in your backend's environment variables / secrets manager — never in code you ship to a browser or app
* **Scope**: unrestricted. Whoever holds it has the same access you do
* **If it leaks**: revoke it immediately from the dashboard and issue a new one. A leaked API key is equivalent to a leaked account password — treat it that way

Because it's this powerful, the API key is never meant to leave your server. That's the entire reason the publishable key exists — to give frontend code a way to trigger calls *without* ever having access to a credential this strong.

***

## Publishable key — limited access, safe for browsers

A publishable key is designed to be safe for use in frontend code. It can be pasted directly into website code that anyone can view in their browser's dev tools.

* **Format**: `oi_pk_...`
* **Lives**: directly in your frontend code (e.g. with the [Web SDK](/concepts/web-sdk)) — this is the intended, safe place for it
* **Scope**: can only do one thing — start a call. It cannot read your data, list your agents, see call history, or change any account settings
* **Domain-locked**: when you create one in the dashboard, you register the origins (domains) it's allowed to be used from — e.g. `https://yoursite.com`. A request from any other origin is rejected with `403 ORIGIN_NOT_ALLOWED`, even with a valid key
* **If it leaks**: low risk by design — it can only start calls on agents you've configured, and only from your registered domains. You can still revoke and rotate it from the dashboard if you want to be safe

This is what makes the Web SDK possible: a website visitor's browser needs *some* credential to start a call, but it can never be trusted with your full API key. The publishable key solves that — full functionality for its one job, zero exposure for everything else.

***

## Why two keys instead of one

A single backend you control can safely hold a powerful, unrestricted key — only your own server code ever touches it. A browser is different: anything you ship to it is visible to whoever opens dev tools, so any key embedded there is effectively public. Rather than force you to proxy every call request through your own server, OneInbox gives you a second key type that's *safe to be public* — scoped down to exactly the one capability a browser legitimately needs, and locked to the domains you control.

|                  | API key                                      | Publishable key                                                       |
| ---------------- | -------------------------------------------- | --------------------------------------------------------------------- |
| Trust model      | Secret — protect like a password             | Public — safe to expose                                               |
| Who/what uses it | Your server                                  | Visitors' browsers                                                    |
| Capabilities     | Full account access                          | Start a call only                                                     |
| Restricted by    | Nothing (full scope)                         | Registered origins (domains)                                          |
| Where to create  | Dashboard → **API Keys**                     | Dashboard → **Publishable Keys**                                      |
| If exposed       | Revoke immediately — full account compromise | Low risk — already designed to be public, but you can still rotate it |

***

## Get your API key

1. [Sign up or log in](https://oneinbox-dashboard.vercel.app/signup) at the OneInbox dashboard
2. Open **API Keys**
3. Click **Create API key**, give it a name, and copy the key

You can view and manage keys anytime from the dashboard — create new keys or revoke old ones as needed.

<Warning>
  Never put your API key in frontend code — anyone who finds it gets full access to your account. If you need to trigger calls from a browser, use a **publishable key** instead (see [Web SDK](/concepts/web-sdk)).
</Warning>

***

## How to send it

Add this header to every request:

```
Authorization: Bearer <api_key>
```

Example:

```bash theme={null}
curl https://api.oneinbox.ai/v1/agents \
  -H "Authorization: Bearer <api_key>"
```

***

## Check usage

Retrieve usage summary for your account — credits consumed, call counts, and billing period.

```bash theme={null}
curl https://api.oneinbox.ai/v1/usage \
  -H "Authorization: Bearer <api_key>"
```

***

## Quick reference

| Action                                    | Where                                                                            |
| ----------------------------------------- | -------------------------------------------------------------------------------- |
| Create or revoke API keys                 | [Dashboard](https://oneinbox-dashboard.vercel.app/signup) → **API Keys**         |
| Create or revoke publishable keys         | [Dashboard](https://oneinbox-dashboard.vercel.app/signup) → **Publishable Keys** |
| Call agents, models, calls, etc. (server) | `Authorization: Bearer <api_key>` on every request                               |
| Start a call from a website (browser)     | Publishable key with the [Web SDK](/concepts/web-sdk)                            |

Full walkthrough → **[Quickstart](/guides/quickstart)**