> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ibee.co.in/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ibee.co.in/docs/_mcp/server.

# Authentication

> Learn how to create API tokens and authenticate your requests.

Every API request must include a valid platform API token. Tokens use Bearer authentication and are scoped to your organization.

## Create an API token

1. Log in to the [IBEE portal](https://portal.ibee.ai).
2. Go to **Settings → API Tokens**.
3. Click **Create Token**.
4. Give the token a name, select the scopes it needs, and choose a workspace policy.
5. Click **Create**. Copy the token immediately — it is shown only once.

> **Warning**
>
> Store your token securely — it cannot be viewed again after creation. If a
> token is lost or exposed, revoke it and create a new one. Never embed a token
> in client-side code (browser or mobile apps) or commit it to source control.

## Using your token

Include the token in the `Authorization` header as a Bearer token:

```bash
curl https://api.ibee.ai/v1/object-storage/buckets?workspace_id=907479 \
  -H "Authorization: Bearer ibee_prod_key_xxxxxxxxxxxx"
```

Production tokens start with `ibee_prod_key_`. Development tokens start with
`ibee_dev_key_` and must be sent to `https://api.ibee.co.in/v1`. Tokens are
environment-specific; a development token is not valid against production and
vice versa.

## Scopes

Each token is granted specific scopes that control which resources it can access. Select the minimum scopes your integration needs.

| Scope                   | Permission                                                               |
| ----------------------- | ------------------------------------------------------------------------ |
| `secret-store.read`     | List stores, get secret metadata and values.                             |
| `secret-store.write`    | Create stores, create and update secrets.                                |
| `object-storage.read`   | List and read buckets.                                                   |
| `object-storage.write`  | Create buckets.                                                          |
| `object-storage.delete` | Delete buckets.                                                          |
| `network.read`          | List VPCs, subnets, NAT gateways, reserved IPs, and firewall resources.  |
| `network.write`         | Create, update, attach, and delete networking resources.                 |
| `load-balancer.read`    | List load balancers and read provisioning status.                        |
| `load-balancer.write`   | Create, update, and delete load balancers.                               |
| `vm.read`               | List and get virtual machines and operations.                            |
| `vm.write`              | Create, update, delete VMs and run power actions.                        |
| `billing.read`          | Check whether a workspace is eligible to create billable resources.      |
| `block-storage.read`    | List volumes and read volume operation history.                          |
| `block-storage.write`   | Create, attach, detach, resize, and delete volumes.                      |
| `cdn.read`              | List CDN distributions, website settings, and custom domains.            |
| `cdn.write`             | Manage distributions, website settings, domains, URLs, and cache purges. |

A request to an endpoint that requires a scope the token does not have returns `403 Forbidden`.

The SDKs and CLI expose an explicit billing eligibility check for previews and
diagnostics. A token needs `billing.read` only when your integration calls that
check directly. Billable create requests need only the corresponding product
write scope: the public gateway makes a fail-closed, authoritative billing
decision before it forwards the request to the existing product service.

## Workspace policies

When you create a token, you choose how it accesses workspaces:

| Policy                  | Behavior                                                                                                  |
| ----------------------- | --------------------------------------------------------------------------------------------------------- |
| **Entire organization** | The token can access any workspace in the organization.                                                   |
| **Specific workspaces** | The token can only access the workspaces you select. Requests to other workspaces return `403 Forbidden`. |

Use **Specific workspaces** when you want to limit a CI/CD pipeline or integration to a single environment (for example, only staging).

## Revoking tokens

To revoke a token:

1. Go to **Settings → API Tokens** in the portal.
2. Find the token and click **Revoke**.

Revoked tokens are rejected immediately on all subsequent requests.

## Error responses

| Status             | Meaning                                                                                         |
| ------------------ | ----------------------------------------------------------------------------------------------- |
| `401 Unauthorized` | The token is missing, malformed, or expired.                                                    |
| `403 Forbidden`    | The token does not have the required scope or is not allowed to access the requested workspace. |