Skip to main content

Authentication

Every Unlayer server-side surface — the Cloud API, the TypeScript SDK, and the CLI — authenticates with a bearer token in the Authorization header:

Authorization: Bearer <your-token>

Three token types are accepted. Token type is auto-detected from the prefix.

PrefixToken typeWhen to use
unlayer_sk_*API KeyServer-side scripts, CI jobs, single-project integrations.
unlayer_pat_*Personal Access TokenPersonal use across multiple projects or workspaces.

Both API Keys and Personal Access Tokens are managed from Console — from a project's Settings sidebar, or all in one place under Profile → API Tokens. The direct URLs below open the same pages.

Getting an API Key (unlayer_sk_*)​

Best for server-side scripts, CI jobs, and single-project integrations. Scoped to one project — pick the project whose templates and data the token should be able to read/write.

  1. Sign in to Console.

  2. Pick the project you want the integration to act on and note its Project ID (it's in the URL once you open the project: console.unlayer.com/<projectType>/<projectId>/...).

  3. Open the project's Settings → API Keys (the v3 entry — not the v2 one, which is a separate legacy key), or navigate directly to:

    https://console.unlayer.com/builder/<projectId>/settings/project-api-keys

    Replace <projectId> with your project's numeric ID.

  4. Under Create New API Key, enter a descriptive name (e.g. "Production", "CI/CD", "Claude Desktop") and click Create.

  5. Copy the value that starts with unlayer_sk_ — it's only shown once.

Show-once secret

API keys are displayed only once at creation time. Store the value in a secret manager or .env file immediately — Console only displays a partial fingerprint after that. If you lose the value, revoke the key and create a new one.

Using it​

# Cloud API (Bearer token, v3 endpoints)
curl -H "Authorization: Bearer unlayer_sk_..." \
  https://api.unlayer.com/v3/templates

# TypeScript SDK
import Unlayer from '@unlayer/sdk';
const client = new Unlayer({ apiKey: process.env.UNLAYER_API_KEY });

Getting a Personal Access Token (unlayer_pat_*)​

Best for personal use when you want one token that works across multiple projects under your account. A PAT inherits your user's access — anywhere you can sign in to, the PAT can act.

  1. Sign in to Console.

  2. Note any Project ID from one of your projects (the route is scoped to a project ID for URL consistency, but the token itself isn't tied to that project).

  3. Open Settings → Personal Access Tokens from any project (or Profile → API Tokens), or navigate directly to:

    https://console.unlayer.com/home/<projectId>/profile/tokens

    Replace <projectId> with any project ID you have access to.

  4. Click Create New Token and fill out:

    • Token Name (e.g. "CLI Token", "My laptop — Claude Desktop").
    • Scope: All Workspaces (cross-workspace access) or Single Workspace (pick one).
    • Expiration: Never or a custom date (up to one year out).

  5. Copy the value that starts with unlayer_pat_ — it's only shown once.

PATs follow the same show-once rule as API keys. Revoke them from the same page if a laptop or client is lost.

Project ID with PATs​

Because a PAT isn't bound to a single project, server endpoints that need to know which project to act on require an explicit projectId query parameter or X-Project-Id header. API keys don't need this — the project is bound to the key on the server.

Security checklist​

  • Server-side only. Never ship API keys or PATs to the browser — they grant full access to your project's data. Always proxy through your backend.
  • Use a secret manager. Don't commit tokens to source control. Use Vercel/Netlify/AWS secret stores, GitHub Actions secrets, etc.
  • Rotate on compromise. If a laptop is lost, a CI job is exposed, or a key leaks into a log — revoke it in Console immediately and issue a new one.
  • Least-privilege scope. Prefer an API key (project-scoped) over a PAT (account-scoped) when the integration only needs one project.
  • Cloud API — REST endpoints these tokens authenticate against.
  • Cloud API reference — full endpoint reference with auth headers shown per operation.
  • CLI — terminal tool for managing templates and projects.
  • TypeScript SDK — programmatic Cloud API client (reads UNLAYER_API_KEY from the environment by default).