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

# Authentication

> Learn how to authenticate with the Widgetic API

The Widgetic API uses Bearer token authentication. All requests must include an `Authorization` header with your API key or editor session token.

## Authentication Methods

### API Keys (Server-Side)

API keys are the recommended authentication method for server-side applications. They provide persistent access without expiration.

```bash theme={null}
Authorization: Bearer wgt_usr_your_api_key_here
```

### Editor Sessions (For Customer Browsers)

To run Widgetic's editors inside your own page for one of your customers, mint a short-lived [editor session](https://widgetic.com/docs/partners/editor-sessions.md) on your server and pass that session token to the browser.

```bash theme={null}
Authorization: Bearer wgt_eds_your_editor_session_token_here
```

## API Key Types and Access Levels

Your API key prefix determines your role and what endpoints you can access:

| Key Prefix | Role | Access Level | Use Case |
| - | - | - | - |
| `wgt_usr_` | User | `user` | Personal account access |
| `wdg_org_` | Organization | `user` | Organization-wide access |
| `wgt_prt_` | Partner | `partner` | White-label integrations |
| `wgt_adm_` | Admin | `admin` | Internal administration |

## Understanding Access Levels

Each API endpoint specifies an `x-access-level` that determines which roles can access it:

* **`public`**: Any authenticated user can access (any key type)
* **`user`**: Requires user-level access or higher
* **`partner`**: Requires partner-level access or higher
* **`admin`**: Requires admin-level access only

> [!NOTE]
>
> The `x-access-level` is a **role gate**, not a visibility gate. All public endpoints appear in the documentation, but your access depends on your key type.

## Limit What a Key Can Do

A key made without a limit has **full access**: it does everything its owner can, and so does every key made before limits existed. A key you put on a build server, or in a partner's backend, needs only the part of the API it uses. Limit it, and a leaked key can do no more than that.

You choose the limit when you make the key, in the dashboard (Workspace settings → API keys) or with `POST /users/{id}/keys` (see [Security](https://widgetic.com/resources/security.md#making-rotating-and-deleting-keys)). Send a `preset` or a list of `scopes`, never both:

| Preset | What the key may do |
| - | - |
| `read_only` | Looks at everything the account holds and changes nothing. It holds `content:read`, `partner:read`, `billing:read` and `account:read`. |
| `content` | Builds and manages widgets and compositions, and runs the AI. It holds `content:read`, `content:write` and `generate`, and touches no billing, no people and no partners. |
| `full_access` | Everything the account owner may do. A key made with neither a preset nor scopes is this. |

When a preset is not enough, name the scopes you want:

| Scope | What it lets a key do |
| - | - |
| `content:read` | Read widgets, compositions, canvases, projects, folders, uploads, translations and the analytics of your content. |
| `content:write` | Create, change, publish and delete the same. Includes `content:read`. |
| `generate` | Run the AI that builds widgets and compositions, and follow or cancel what it is doing. This spends credits. |
| `partner:read` | Read managed users, what they spent, presets, the contract and the storage destination (partners). |
| `partner:write` | Create, change and delete managed users and presets (partners). Includes `partner:read`. |
| `billing:read` | Read credits, usage, invoices, subscriptions and payment methods. |
| `billing:write` | Buy credits, pay invoices, change a subscription or a payment method. Includes `billing:read`. |
| `account:read` | Read the profile, organizations and members, allowed domains, notices, the names of API keys and the [Brand Kit](https://widgetic.com/docs/partners/brand-kit.md). |
| `account:write` | Change the profile, organizations and members, allowed domains and integrations. Includes `account:read`. |

* **Writing includes reading.** Naming `content:write` gives `content:read` too, and the same goes for the other `write` scopes. A list that names every scope makes a key with full access.
* **Scopes only narrow.** A limited key still needs what its owner needs: the role, the plan and, for a [partner](https://widgetic.com/docs/partners/account-status.md), an account in force.
* **The limit is fixed when the key is made.** To widen it, make a new key and delete the old one.
* **A limited key cannot make itself a bigger one.** Making, changing and deleting keys, exchanging tokens, signing in and the administration routes need full access.
* **Changing the Brand Kit needs full access**, because a change reshapes every widget the account makes from then on. A key with `account:read` may look at it. See [Brand Kit](https://widgetic.com/docs/partners/brand-kit.md).
* **The MCP server needs full access.** `https://mcp.widgetic.com` hands an assistant every tool your account has, so only a key made with full access opens it, and a limited key is refused with `403`. See [Authentication for AI assistants](https://widgetic.com/docs/agents/authentication.md#api-keys).
* **A partner's backend needs three scopes to start an editor session** for a managed user: `partner:write`, `content:write` and `generate` together. See [Editor Sessions](https://widgetic.com/docs/partners/editor-sessions.md#make-a-session).

A request outside the scopes of the key is refused with `403` and the code `API_KEY_SCOPE_MISSING`. `error.details.missingScopes` lists what a new key needs, and `error.details.fullAccessRequired` is `true` when no list of scopes would have been enough:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "API_KEY_SCOPE_MISSING",
    "message": "This API key may not do this: it lacks the content:write scope (it holds content:read, partner:read, billing:read, account:read). The scopes of a key cannot be changed once it is made, so make a new key that includes them.",
    "details": {
      "missingScopes": ["content:write"],
      "fullAccessRequired": false
    }
  }
}
```

> [!NOTE]
>
> These scopes belong to the key and last as long as it does. To give a customer's browser limited, short-lived access to only that customer's content, mint an [editor session](https://widgetic.com/docs/partners/editor-sessions.md) on your server instead.

## Validating Tokens

You can validate a token to check its status and associated permissions:

```bash theme={null}
curl -X GET "https://api.widgetic.com/v1/tokens/validate" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

Response:

```json theme={null}
{
  "success": true,
  "data": {
    "valid": true,
    "tokenType": "api_key",
    "scopes": ["content:read", "content:write"],
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "expiresAt": null
  }
}
```

## Best Practices

> [accordion] Keep API Keys Secure
>
> * Never expose API keys in client-side code
> * Use environment variables to store keys
> * Rotate keys periodically
> * Use the token exchange flow for browser applications

> [accordion] Use Appropriate Key Types
>
> * Use `wgt_usr_` keys for personal development
> * Use `wdg_org_` keys for organization-wide applications
> * Use `wgt_prt_` keys for partner integrations

> [accordion] Handle Token Expiration
>
> * JWT tokens expire after a set period
> * Implement token refresh logic in your application
> * Use the SDK's async token provider for automatic handling

## Error Responses

When authentication fails, you'll receive one of these responses:

| Status | Code | Description |
| - | - | - |
| 401 | `UNAUTHORIZED` | Missing or invalid authentication token |
| 403 | `FORBIDDEN` | Token valid but insufficient permissions |

Example error response:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions for this endpoint",
    "correlationId": "req_123e4567-e89b-12d3-a456-426614174000"
  }
}
```

## Next Steps

> [card] [Partner Authentication](https://widgetic.com/docs/partners/overview.md)
>
> Learn about partner-specific authentication flows

> [card] [API Reference](https://widgetic.com/api-reference/introduction.md)
>
> Explore all available endpoints


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