Overview

Customize the look and feel of your authentication pages to match your brand. Configure logos, colors, custom domains, and more.

Custom Domains

Use your own domain for authentication pages (e.g., auth.yourcompany.com).

Add Custom Domain

const domain = await client.auth.branding.addDomain({
  domain: 'auth.yourcompany.com',
});
 
console.log('Verification method:', domain.verification.method);
console.log('Verification value:', domain.verification.value);

Verify Domain

DNS TXT Record:

Add a TXT record to your DNS:

_transactional-verify.auth.yourcompany.com TXT "verify-xxxxx"

CNAME Record:

Add a CNAME record:

auth.yourcompany.com CNAME auth-cname.usetransactional.com

// After adding DNS records
await client.auth.branding.verifyDomain('auth.yourcompany.com');

SSL Certificate

SSL certificates are automatically provisioned and renewed via Let's Encrypt.

Logo and Branding

Configure Branding

TypeScript:

await client.auth.branding.update({
  logo: 'https://yourcompany.com/logo.png',
  logoDark: 'https://yourcompany.com/logo-dark.png', // For dark mode
  favicon: 'https://yourcompany.com/favicon.ico',
 
  colors: {
    primary: '#0066cc',
    accent: '#00cc66',
    background: '#ffffff',
    backgroundDark: '#1a1a1a',
    text: '#333333',
    textDark: '#ffffff',
  },
 
  typography: {
    fontFamily: 'Inter, system-ui, sans-serif',
  },
});

Python:

client.auth.branding.update(
    logo="https://yourcompany.com/logo.png",
    logo_dark="https://yourcompany.com/logo-dark.png",
    favicon="https://yourcompany.com/favicon.ico",
    colors={
        "primary": "#0066cc",
        "accent": "#00cc66",
        "background": "#ffffff",
    },
)

Page Copy

await client.auth.branding.update({
  loginPage: {
    title: 'Welcome back',
    subtitle: 'Sign in to your account',
    welcomeMessage: 'Enter your credentials to continue',
  },
});

await client.auth.branding.update({
  socialLogin: {
    position: 'top', // 'top', 'bottom', or 'hidden'
    buttonStyle: 'icon', // 'icon', 'text', or 'full'
    separator: 'or continue with', // Text between social and email
  },
});

Footer

await client.auth.branding.update({
  footer: {
    showPoweredBy: false, // Hide "Powered by Transactional"
    links: [
      { text: 'Privacy', url: 'https://yourcompany.com/privacy' },
      { text: 'Terms', url: 'https://yourcompany.com/terms' },
      { text: 'Help', url: 'https://yourcompany.com/help' },
    ],
    copyrightText: '© 2024 Your Company',
  },
});

Custom CSS

For advanced customization, add custom CSS:

await client.auth.branding.update({
  customCss: `
    .login-card {
      border-radius: 16px;
      box-shadow: 0 4px 20px rgba(0, 0, 0, 0.1);
    }
 
    .btn-primary {
      background: linear-gradient(135deg, #0066cc, #0044aa);
      border-radius: 8px;
    }
 
    .social-button {
      border: 2px solid #e0e0e0;
    }
  `,
});

Available CSS Classes

Class	Element
`.login-card`	Main login container
`.login-header`	Header with logo
`.login-title`	Title text
`.login-subtitle`	Subtitle text
`.form-input`	Input fields
`.btn-primary`	Primary buttons
`.btn-secondary`	Secondary buttons
`.social-button`	Social login buttons
`.error-message`	Error messages
`.footer`	Page footer

Email Templates

Customize authentication emails:

Verification Email

await client.auth.branding.updateEmailTemplate('verification', {
  subject: 'Verify your email for {{company_name}}',
  htmlBody: `
    <h1>Verify your email</h1>
    <p>Hi {{user_name}},</p>
    <p>Click the link below to verify your email:</p>
    <a href="{{verification_url}}">Verify Email</a>
  `,
  textBody: `
    Verify your email
 
    Hi {{user_name}},
 
    Click the link to verify: {{verification_url}}
  `,
});

Available Email Templates

Template	Purpose
`verification`	Email verification
`password_reset`	Password reset
`welcome`	Welcome email after signup
`mfa_code`	MFA verification code
`invitation`	Organization invitation
`login_notification`	New login detected

Template Variables

Variable	Description
`{{user_name}}`	User's display name
`{{user_email}}`	User's email
`{{company_name}}`	Your company name
`{{verification_url}}`	Verification link
`{{reset_url}}`	Password reset link
`{{code}}`	Verification code
`{{expiry_time}}`	Link/code expiration

Security Badges

Show trust indicators on login pages:

await client.auth.branding.update({
  securityBadges: {
    show: true,
    badges: [
      'soc2', // SOC 2 compliance
      'gdpr', // GDPR compliance
      'ssl',  // SSL secured
    ],
  },
});

Preview Changes

Preview branding changes before publishing:

const preview = await client.auth.branding.preview({
  logo: 'https://yourcompany.com/new-logo.png',
  colors: {
    primary: '#ff0000',
  },
});
 
console.log('Preview URL:', preview.url);
// Opens a preview of the login page with changes

Organization Branding

Override branding for specific organizations:

await client.auth.organizations.update('org_xxx', {
  branding: {
    logo: 'https://acme.com/logo.png',
    colors: {
      primary: '#0066cc',
    },
  },
});

Organization branding takes precedence when users authenticate in that organization's context.

Branding Presets

Use pre-built themes:

// Apply a preset theme
await client.auth.branding.applyPreset('modern-dark');
 
// Available presets:
// - 'default'
// - 'modern-light'
// - 'modern-dark'
// - 'minimal'
// - 'corporate'

Asset Management

Upload Assets

// Upload logo
const logo = await client.auth.branding.uploadAsset({
  file: logoFile,
  type: 'logo',
});
 
console.log('Logo URL:', logo.url);

List Assets

const assets = await client.auth.branding.listAssets();
 
for (const asset of assets) {
  console.log(`${asset.type}: ${asset.url}`);
}

Get Current Branding

const branding = await client.auth.branding.get();
 
console.log('Logo:', branding.logo);
console.log('Primary color:', branding.colors.primary);
console.log('Custom domain:', branding.customDomain);

Best Practices

1. Consistent Branding

Use the same logo and colors as your main application
Match typography and button styles
Ensure brand recognition

2. Accessibility

Maintain sufficient color contrast
Use readable font sizes
Test with screen readers

3. Mobile Optimization

Test login pages on mobile devices
Ensure buttons are tap-friendly
Verify logo sizing on small screens

4. Security Perception

Show security badges to build trust
Use professional, clean designs
Display clear privacy policy links

Next Steps

Security - Configure security policies
Webhooks - Track authentication events
API Reference - Complete API documentation