---
title: Authentication
description: Bearer tokens, the four token families, and how roles gate what a token can do.
canonical_url: https://wiblo.app/docs/developers/api/authentication
last_updated: 2026-07-28T17:12:38+02:00
md_url: https://wiblo.app/docs/developers/api/authentication.md
---

# Authentication

Every authenticated request sends a bearer token:

```bash
curl https://api.wiblo.app/v1/me \
  -H "Authorization: Bearer $WIBLO_TOKEN"
```

## Token families

All Wiblo tokens start with `wbl_` and are shown to you exactly once, at mint time.

| Prefix | What it is | Where it comes from |
| --- | --- | --- |
| `wbl_user_` | Personal CLI token acting as you | `wiblo login` (device flow) or Settings → Tokens |
| `wbl_ephem_user_` | Short-lived personal token | Minted for one session, expires on its own |
| `wbl_live_` | Workspace API key acting as a machine member | Workspace settings → API keys |
| `wbl_ephem_ws_` | Short-lived workspace key | Minted per agent-run session |

Personal tokens act with your identity across your workspaces. Workspace API keys act as a **machine member** of one workspace only — they cannot call user-scoped endpoints like `/v1/me` or `/v1/workspaces`.

## Roles

Authorization is role-based — there are no OAuth-style scopes.

- Members hold a role: `owner`, `admin`, or `member`. Machine members never hold `owner`.
- A workspace API key carries a **role cap** (`admin` or `member`); its effective role is the lower of the machine member's role and the cap.
- A handful of sensitive operations (minting and rotating keys, creating invites, approving a CLI sign-in) are **session-only**: they reject every `wbl_*` token and require a signed-in browser session.

## Failure behaviour

A missing token on an authenticated endpoint returns `401 UNAUTHENTICATED`. A token that is wrong, revoked, expired, or from an archived workspace always returns the same `401 INVALID_TOKEN` — the API never reveals which of those it was. A valid token used above its role returns `403` with a code like `INSUFFICIENT_PRIVILEGE`, `ADMIN_REQUIRED`, or `OWNER_REQUIRED`.

> **Tokens are secrets**
>
> A token grants its holder everything the token can do. Keep tokens in your secret manager, prefer ephemeral tokens for automation, and rotate or revoke from the Tokens and API keys pages the moment one may have leaked.