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.

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 on your server and pass that session token to the browser.

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

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). 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.
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, 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.
• 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.
• 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.

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:

{
  "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
    }
  }
}

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 on your server instead.

​

Validating Tokens

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

curl -X GET "https://api.widgetic.com/v1/tokens/validate" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

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

​

Best Practices

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

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

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:

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

​

Next Steps

Partner Authentication

Learn about partner-specific authentication flows

API Reference

Explore all available endpoints