JWT Templates

Customize the claims in your application's access tokens.

Introduction

JWT templates allow you to customize the claims in your application’s access tokens issued by WorkOS. You can leverage core attributes of users and organizations, in addition to custom metadata you set on these objects.

Create a JWT template

JWT templates are managed in the Authentication section of the WorkOS Dashboard. Under the sessions section, choose Configure JWT Template.

WorkOS dashboard demonstrating the position of the "Configure JWT template" button

JWT templates are comprised of a template string which is rendered with the user and organization context after a user successfully authenticates.

Example usage

JavaScript

 {
    "urn:myapp:full_name": "{{ user.first_name || 'Someone' }} {{ user.last_name || 'Unknown' }}",
    "urn:myapp:email": {{ user.email }},
    "urn:myapp:organization_tier": "{{ organization.metadata.tier || 'bronze' }}",
    "urn:myapp:user_language": "{{ user.metadata.language || 'en' }}",
    "urn:myapp:organization_domain": "{{ organization.domains.0.domain }}"
}

 {
    "user": {
        "id": "user_01JNS7VK1HMX7CT0C6V4ZHZZNX",
        "metadata": {
            "language": "es"
        },
        "object": "user",
        "created_at": "2021-01-01T00:00:00.000Z",
        "updated_at": "2021-01-01T00:00:00.000Z",
        "email": "user@example.com",
        "first_name": "User",
        "last_name": "Test",
        "email_verified": true,
        "profile_picture_url": "https://example.com/profile.jpg",
        "external_id": "user_123"
    },
    "organization": {
        "name": "Test Organization",
        "id": "org_01JNS7VK1HMX7CT0C6V4ZHZZNX",
        "metadata": {},
        "object": "organization",
        "created_at": "2021-01-01T00:00:00.000Z",
        "updated_at": "2021-01-01T00:00:00.000Z",
        "allow_profiles_outside_organization": false,
        "domains": [
            {
                "id": "org_domain_01JNS7VK1HMX7CT0C6V4ZHZZNX",
                "domain": "acme.com",
                "object": "organization_domain",
                "organization_id": "org_01JNS7VK1HMX7CT0C6V4ZHZZNX",
                "state": "verified"
            },
            {
                "id": "org_domain_01JNS7VK1HMX7CT0C6V4ZHZZNY",
                "domain": "example.com",
                "object": "organization_domain",
                "organization_id": "org_01JNS7VK1HMX7CT0C6V4ZHZZNX",
                "state": "verified"
            }
        ],
        "stripe_customer_id": "cus_123",
        "external_id": "org_123"
    }
}

 {
    "urn:myapp:full_name": "User Test",
    "urn:myapp:email": "user@example.com",
    "urn:myapp:organization_tier": "bronze",
    "urn:myapp:user_language": "es",
    "urn:myapp:organization_domain": "acme.com"
}

Syntax

1. Basic Variable Interpolation

You can reference variables inside the template.

JavaScript

 {
    "user": {{ user.first_name }}
}

 {
    "user": {
      "first_name": "Alice"
    }
  }

 {
    "user": "Alice"
}

2. Fallback Values (`||` operator)

If the first value is null or undefined, the next value in the fallback chain is used.

JavaScript

 {
    "user": {{ user.metadata.nickname || user.email }}
}

 {
  "user": {
    "email": "alice@example.com"
  }
}

 {
    "user": "alice@example.com"
}

3. String Literals

Strings can be used as fallback values.

JavaScript

 {
    "user": {{ user.metadata.nickname || 'Guest' }}
}

 {
  "user": {}
}

 {
    "user": "Guest"
}

4. Concatenation in Strings

Multiple variables can be used within a single string.

JavaScript

 {
    "user": "{{ user.first_name }} {{ user.last_name }}"
}

 {
  "user": {
    "first_name": "Alice",
    "last_name": "Smith"
  }
}

 {
    "user": "Alice Smith"
}

5. Object Interpolation

Interpolating entire objects and arrays is allowed if they are valid JSON objects. This is not allowed inside string literals and will throw a validation error.

JavaScript

 {
  "metadata": {{ user.metadata }}
}

 {
  "user": {
    "metadata": {
      "role": "admin"
    }
  }
}

 {
    "metadata": {
        "role": "admin"
    }
}

6. Reserved Keys Restriction

The following keys cannot be used in templates:

iss

sub

exp

iat

nbf

jti

Any attempt to use these keys will result in a validation error.

Whitespace Handling

The rendering engine trims whitespace from the beginning and end of string values.

Error Handling

If the template contains invalid syntax, an error will be thrown:

Template must render to an object: If the template does not evaluate to a valid JSON object (e.g., an array or primitive value). Example:

 [ {{ user.email }} ]

Keys reserved (iss, sub, exp, etc.): These keys cannot be used in the template.

 { "iss": {{ user.email }} }

String encapsulated expression cannot contain object reference: Objects cannot be interpolated inside a string.

 { "user": "{{ user.metadata }}" }

Invalid expression segment: Logical operators (|| with empty operands) or malformed expressions are not allowed.

 {{ user.email && user user }}
{{ user.email || || user.email }}

Template parse error: missing ’}}’: A template block was opened but never closed.

 {{ user.id

Expression cannot be empty: An empty expression inside {{ }} is invalid.

 {{}}

Missing closing braces: Template parse error: missing '}}'

Invalid key usage: Keys reserved (iss, sub, exp, etc.)

Unknown variables: Invalid path: "unknown.variable"

Null Handling

JWT templates provide built-in handling for null values to ensure access tokens only contain populated claims.

1. Removing Top-Level Null Values

If an expression evaluates to null, the corresponding key is removed from the final JSON output.

Example

JavaScript

 {
  "user": {{ user.metadata.favorite_color }},
  "organization_tier": {{ organization.metadata.tier }}
}

 {
  "user": {
    "metadata": {}
  },
  "organization": {
    "metadata": {
      "tier": "bronze"
    }
  }
}

 {
    "organization_tier": "bronze"
}

2. Handling Null Values in Concatenated Strings

If a null value appears in a string concatenation, it is replaced with an empty string ("") instead of being removed.

JavaScript

 {
  "user": "{{ user.first_name }} {{ user.last_name }}"
}

 {
  "user": {
    "first_name": "Alice",
    "last_name": null
  }
}

 {
    "organization_tier": "bronze"
}

3. Using Fallbacks to Avoid Null Values

The || operator can be used to provide a fallback value when an expression evaluates to null.

JavaScript

 {
  "external_id": {{ user.external_id || 'unknown' }}
}

 {
  "user": {
    "external_id": null
  }
}

 {
    "external_id": "unknown"
  }

Size limits

JWT templates must render to a JSON object that is 3072 bytes or smaller due to cookie size constraints in web browsers.

JWT Templates

Introduction

Create a JWT template

Example usage

Syntax

1. Basic Variable Interpolation

2. Fallback Values (|| operator)

3. String Literals

4. Concatenation in Strings

5. Object Interpolation

6. Reserved Keys Restriction

Whitespace Handling

Error Handling

Null Handling

1. Removing Top-Level Null Values

Example

2. Handling Null Values in Concatenated Strings

3. Using Fallbacks to Avoid Null Values

Size limits

2. Fallback Values (`||` operator)