Skip to main content
Unlayer Docs

Authentication

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

Authorization: Bearer <your-token>

API Keys and PATs work with the Cloud API and MCP. OAuth access tokens are resource-bound to MCP and cannot be used directly against Cloud API routes.

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.
(OAuth JWT)OAuth 2.1 access tokenInteractive MCP clients such as Claude and ChatGPT.

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. Don't have an Unlayer account? Sign up free. 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, or sign up free.

  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, or sign up free.

  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.

OAuth (no manual token)​

Live for Unlayer MCP

OAuth browser sign-in is live for the Unlayer MCP server. OAuth-capable clients can connect now without asking users to generate or paste a token.

You won't generate OAuth tokens by hand — the MCP client does it for you. Unlayer's implementation follows the MCP authorization spec:

The resource binding is retained across refreshes. Clients may repeat the MCP resource in a refresh request or omit it; if they send a different resource, Unlayer rejects the refresh.

This lets Claude Desktop, ChatGPT, and other OAuth-capable clients connect with a browser-based "Sign in with Unlayer" flow. The browser handles consent, while the client stores the resulting bearer token and refreshes it automatically. CI should continue to use a project-scoped API key rather than trying to automate an interactive OAuth consent flow.

See the MCP page for connection instructions.

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).
  • MCP — Model Context Protocol server with the same token model + OAuth.