Skip to main content

api-token-usage

title: Using Power Tokens sidebar_position: 8​

Using Power Tokens

Power Tokens are a streamlined way to access Minimal APIs — including System APIs, Auto APIs, Custom APIs, and Apps — without passing individual context headers. A single token encodes the org, project, space, and user identity, making it ideal for external integrations, public dashboards, and shared app access.

How It Works​

When a Power Token is used, you do not need to pass the following headers:

  • X-Org-Id
  • X-Project-Id
  • X-Space-Id
  • X-Feature-Id
  • X-User-Id
  • X-User-Roles

Instead, pass the token in both of the following:

  1. Header — X-Power-Token: <token>
  2. Query parameter — pwt=<token>

Both must be present in every request.

Request Format​

GET https://demo.littlebit.in/minimal/api/rest/v1/<org-slug>/<project-slug>/your-endpoint?pwt=min_xxxx
X-Power-Token: min_xxxx

Example — cURL​

curl --location 'https://demo.littlebit.in:443/minimal/api/rest/v1/acme/tunes/users?pwt=min_qqMU••••••••••••••••••••••••••••••••••••I4I' \
--header 'X-Power-Token: min_qqMU••••••••••••••••••••••••••••••••••••I4I'
note

The pwt query parameter and X-Power-Token header must both carry the same token value in every request.

Access Levels​

The key_type set during token creation determines what operations the token can perform:

key_typePermitted Operations
r--Read only (GET)
-w-Write only (POST, PUT)
--dDelete only (DELETE)
-wdwrite,Delete (DELETE)
r-dread,delete (DELETE)
rw-Read + Write
rwdFull access — Read, Write, Delete
warning

Tokens with admin in their roles field can also access System APIs. Issue admin tokens only to trusted server-side consumers — never expose them in client-side or browser code.

Public App Sharing​

Minimal Apps are publicly shareable. When embedding or sharing an app externally, always back it with a read-only token (key_type: r--) to prevent unintended writes or deletions.

# Good — read-only token for a public dashboard app
curl 'https://demo.littlebit.in:443/minimal/rest/apps/v1/detail?format=xml&app_id=01KKYFKGJ3Y7X6P814TTEJ6SEG&pwt=min_readonlytoken' \
--header 'X-Power-Token: min_readonlytoken'
tip

When creating an app intended for public sharing, generate a dedicated r-- token scoped to that use case. Avoid reusing admin or write-capable tokens in publicly accessible URLs.

Hiding Tokens with Nginx Reverse Proxy​

If you don't want external users to see the app_id, pwt, or the upstream Minimal URL, configure Nginx as a reverse proxy. The token and app ID are injected server-side — the external consumer calls a clean, opaque URL and has no visibility into the underlying Minimal infrastructure.

How It Works​

External User Your Nginx Server Minimal Backend | | | | GET /dashboard | | |------------------------------->| | | | GET /minimal/rest/apps/v1/detail| | | ?format=xml | | | &app_id=01KKYFKGJ3Y7X6P814... | | | &pwt=min_qqMU••••... | | | X-Power-Token: min_qqMU•••• | | |--------------------------------->| | | | | HTML Response | HTML Response | |<-------------------------------|<---------------------------------|

Nginx Configuration​

server {
    listen 443 ssl;
    server_name yourdomain.com;

    # Serve the app at a clean public path
    location /dashboard {
        # Proxy to the Minimal app detail endpoint
        proxy_pass https://demo.littlebit.in:443/minimal/rest/apps/v1/detail?format=xml&app_id=01KKYFKGJ3Y7X6P814TTEJ6SEG&pwt=min_qqMU••••••••••••••••••••••••••••••••••••I4I;

        # Inject the power token header server-side
        proxy_set_header X-Power-Token "min_qqMU••••••••••••••••••••••••••••••••••••I4I";

        # Strip original host so Minimal receives the correct host
        proxy_set_header Host demo.littlebit.in;

        # Do not forward the original Authorization or context headers
        proxy_set_header X-Org-Id "";
        proxy_set_header X-User-Id "";

        proxy_ssl_server_name on;
        proxy_http_version 1.1;
    }
}
tip

You can map multiple clean paths (e.g., /sales-dashboard, /ops-report) each to a different app_id and scoped read-only token — all without exposing any Minimal internals to the end user.

warning

Never log the pwt value or X-Power-Token header in your Nginx access logs. Add the following to your Nginx config to suppress sensitive query parameters from logs:

log_format safe '$remote_addr - [$time_local] "$request_method $uri $server_protocol" $status';
access_log /var/log/nginx/access.log safe;

Where Power Tokens Work​

API TypeSupported
Auto APIs (generated REST endpoints)✅
Custom APIs✅
System APIs (requires admin role in token)✅
Apps (detail / render)✅
Personas✅

Security Guidelines​

  • Never expose write or admin tokens in frontend code, browser URLs, or public repositories
  • Use read-only tokens (r--) for any publicly shared app or embeddable dashboard
  • Use Nginx reverse proxy to hide app_id, pwt, and upstream URLs from external consumers
  • Rotate tokens periodically — delete old tokens via the Delete Token endpoint
  • One token per integration — issue purpose-specific tokens rather than reusing a single token across multiple apps or consumers
  • Tokens are not recoverable after creation — store them securely at the point of issuance

Common Errors​

CodeCause
401X-Power-Token header or pwt query parameter is missing
403Token does not have sufficient key_type permissions for the requested operation
403Token roles do not include admin but a System API was accessed
404Token is invalid or has been deleted