Brand template tokens are JWTs that identify a specific Canva brand template context. They are used to verify requests that need access to brand-template-scoped data.

Canva's internal "Context JWT" is broader, but this package exposes a focused brand template verifier because the generic Context JWT concept is not currently a public Canva Dev surface. This keeps the public API simple today, and allows a more generic verifier to be introduced later when external migration begins.

The verifier caches JWKS public keys according to the configured cache settings. Create one verifier instance and reuse it for all verification requests.

Usage

Basic usage:

import { initBrandTemplateTokenVerifier } from '@canva/app-middleware';

// Initialize once at app startup
const verifier = initBrandTemplateTokenVerifier({
  appId: process.env.CANVA_APP_ID,
});

// Verify tokens per request inside a handler
const payload = await verifier.verify(token);
console.log(payload.brand_template_id, payload.appId);

TYPESCRIPT

With custom options:

const verifier = initBrandTemplateTokenVerifier({
  appId: process.env.CANVA_APP_ID,
  cacheMaxAgeMinutes: 30,
  timeoutMs: 10000,
});

TYPESCRIPT

Parameters

optionsTokenVerifierOptions

Required

Configuration options for the verifier

appIdstring

Required

The ID of the Canva app, obtained via the developer portal canva.com/developers.

cacheMaxAgeMinutesnumber

Optional

The maximum age of the JWKS cache in minutes.

Default value: 60

timeoutMsnumber

Optional

The timeout for the JWKS fetch in milliseconds.

Default value: 30000

baseUrlstring

Optional

The base URL for the JWKS endpoint.

Default value: "https://api.canva.com"

Returns

A configured verifier instance.

verifyfunction

Verifies a Canva brand template JWT token and returns the decoded payload.

Parameters

tokenstring

Required

The JWT token to verify

Returns

The verified brand template token payload. This is a Promise that resolves with the following object:

appIdstring

The ID of the Canva app

brandTemplateIdstring

The ID of the Canva brand template

Throws

When the token is malformed or has an invalid signature

Throws

When the token has expired