API tokens for CLI installs.
Dashboard API tokens let the Wensity CLI install Pro components and premium blocks without putting your browser session cookie in a terminal. You create tokens in the dashboard, save them in wensity login, and the CLI sends them as bearer credentials on authenticated source requests.
Wensity stores only a SHA-256 hash of each token. The raw wensity_... secret is shown once at creation time. Revoked tokens stop working on the next whoami, add, or update request.
This page covers token creation, CLI usage, the bearer endpoints that accept tokens, published rate limits, and the error codes you are most likely to see during installs.
How tokens work
Copy the raw token when it is created. Wensity cannot recover a lost secret later.
Only the SHA-256 hash is saved in the database.
Dashboard revocation takes effect immediately on the next authenticated CLI request.
A token inherits the component access of the account that created it.
You can keep up to 20 active tokens per account. Email verification is required before creating a new token.
Create a token
Open Dashboard API Tokens, choose a short name, create the token, and copy it before closing the reveal dialog.
Use with the CLI
The CLI stores credentials at ~/.config/wensity/credentials.json with 0600 permissions.
$pnpm dlx wensity login --token "$WENSITY_TOKEN"$pnpm dlx wensity whoami$pnpm dlx wensity add <pro-component-slug>$pnpm dlx wensity add <block-slug> --type block
You can pass WENSITY_TOKEN directly to wensity login, or use WENSITY_CREDENTIALS_FILE when your environment needs a custom credential path.
For a direct HTTP check, send the token as a bearer header:
$curl -H "Authorization: Bearer $WENSITY_TOKEN" \$https://ui.wensity.com/api/cli/whoami
Free component installs can still use the public registry without a token. Pro components and premium blocks require a saved token and an active component license.
Bearer CLI endpoints
After wensity login, the CLI sends your saved token as an Authorization: Bearer header to /api/cli/* only.
| Endpoint | Purpose |
|---|---|
| GET /api/cli/whoami | Validates the token and returns account, plan, and entitlement state. |
| GET /api/cli/<slug> | Returns Pro component source for CLI installs. |
| GET /api/cli/blocks/<slug> | Returns premium block source for wensity add <slug> --type block. |
Browser source in the marketplace uses cookie sessions on /api/registry/<slug>/source instead of API tokens. See Components for that path.
Dashboard token endpoints
Create, list, and revoke tokens from the dashboard UI. These routes use your signed-in browser session, not a bearer token.
| Endpoint | Purpose |
|---|---|
| GET /api/tokens | Lists API tokens for the signed-in account. |
| POST /api/tokens | Creates a token and returns the raw secret once. |
| DELETE /api/tokens/<id> | Revokes one token for the signed-in owner. |
Rate limits
These are the published limits CLI and dashboard clients should design around.
| Scope | Limit |
|---|---|
| Active API tokens | 20 per account |
| POST /api/tokens | 5 create attempts per hour per signed-in user |
| GET /api/cli/whoami and authenticated CLI source routes | 120 requests per minute per API token |
| GET /api/registry | 60 requests per minute per IP for public metadata |
Rate-limited responses return 429 with RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Retry-After, X-RateLimit-Scope, X-RateLimit-Source, and X-Request-Id headers.
Template downloads, checkout, and other marketplace routes have their own limits. See Templates and Billing for those flows.
Errors
CLI (/api/cli/*)
Bearer CLI routes return structured JSON errors. The CLI prints the message and exits with code 1.
{"error": "pro_license_required","message": "This component requires an active Wensity Pro component license."}
| Code | Meaning |
|---|---|
| missing_token | A Pro CLI endpoint was called without a bearer token. |
| invalid_token | The token hash does not match a stored credential. |
| token_revoked | The token was revoked in the dashboard. |
| token_user_missing | The token owner no longer exists. |
| pro_license_required | The account has no active component license. |
| component_not_found | The component slug is missing from the registry. |
| block_not_found | The block slug is missing from the registry. |
| component_source_unreadable | Component source storage cannot be read server-side. |
| block_source_unreadable | Block source storage cannot be read server-side. |
| rate_limit_exceeded | The request exceeded a published rate limit. |
Dashboard token creation (POST /api/tokens)
Session-authenticated token management can return errors that never appear on CLI bearer routes.
| Code | Meaning |
|---|---|
| email_not_verified | Token creation requires a verified email address on the signed-in account. |
| rate_limit_exceeded | More than 5 create attempts in the current hour. |
Keep secrets safe
Treat a wensity_... token like a deploy secret. Create one token per machine or CI environment, name tokens clearly, and revoke lost tokens from the dashboard instead of trying to recover them.
Never print tokens in CI logs, commit them to git, paste them in bug reports, or embed them in browser JavaScript. Use wensity logout on shared machines.