@meistrari/auth-nuxt

A Nuxt module for authentication, organization management, and API key capabilities.

Auth Types

This SDK supports two interactive authentication models:

• Application Authentication (recommended): Use this for product applications that need end-user authentication and authorization scoped to a specific application. See Application Authentication Guide.
• First-Party Authentication: Use this only for trusted first-party tools that interact directly with the Auth API in an administrative way, such as the Accounts Dashboard and Backoffice. See First-Party Authentication Guide.

For machine-to-machine authentication, use @meistrari/auth-core directly on the server. See the Client Credentials Guide.

Installation

bun add @meistrari/auth-nuxt

Quick Start

export default defineNuxtConfig({
  modules: ['@meistrari/auth-nuxt'],
  telaAuth: {
    apiUrl: 'https://auth.tela.com',
    application: {
      enabled: true,
      dashboardUrl: 'https://accounts.tela.com',
      applicationId: 'app_123',
      redirectUri: 'https://your-app.com/auth/callback',
    },
  },
})

Application auth auto-imports useTelaApplicationAuth() and the application-mode useTelaOrganization(), registers <TelaRole>, installs role directives, and adds SDK routes under /auth/* plus /api/auth/api-key/** and /api/auth/organization/**. useTelaApiKey() is also available; in application mode it targets the local API key proxy for app-scoped user API keys.

First-party auth auto-imports useTelaSession(), useTelaSessionAssurance(), useTelaOrganization(), and useTelaApiKey().

Runtime configuration

Set deployment-specific values under runtimeConfig.telaAuth. These take precedence over telaAuth module options, which provide defaults (including nested application settings).

export default defineNuxtConfig({
  modules: ['@meistrari/auth-nuxt'],
  telaAuth: {
    application: { enabled: true },
  },
  runtimeConfig: {
    telaAuth: {
      apiUrl: '',
      application: {
        applicationId: '',
        dashboardUrl: '',
        redirectUri: '',
      },
    },
  },
})

Override these values in the deployed server's environment without rebuilding:

NUXT_TELA_AUTH_API_URL=https://auth.example.com
NUXT_TELA_AUTH_ISSUER=https://auth.example.com
NUXT_AUTH_API_INTERNAL_URL=http://auth-api:3001
NUXT_TELA_AUTH_JWT_COOKIE_NAME=my-jwt
NUXT_TELA_AUTH_APPLICATION_APPLICATION_ID=app_123
NUXT_TELA_AUTH_APPLICATION_DASHBOARD_URL=https://accounts.example.com
NUXT_TELA_AUTH_APPLICATION_REDIRECT_URI=https://app.example.com/auth/callback
NUXT_TELA_AUTH_APPLICATION_LOGIN_PATH=/login
NUXT_TELA_AUTH_APPLICATION_UNAUTHORIZED_PATH=/unauthorized

The module declares these runtime keys even when omitted from your config. Server handlers read runtimeConfig.telaAuth; the SDK copies its supported settings to runtimeConfig.public.telaAuth per request for browser composables and plugins. These settings are public: do not use them for credentials or secrets.

issuer is the exact expected iss claim of application JWTs (the Auth API's BETTER_AUTH_URL). It defaults to apiUrl when empty. Set it explicitly when the URL used to reach Auth differs from its public identity. The internal URL controls server-side transport and JWKS retrieval; it must not replace the expected issuer. Neither the issuer nor the audience check is disabled.

NUXT_AUTH_API_INTERNAL_URL sets the internal URL. A bare AUTH_API_INTERNAL_URL is read only when the NUXT_ variable is empty.

application.enabled and skipServerMiddleware select registrations at build time; set them in telaAuth or runtimeConfig.telaAuth before building. Changing those flags in the deployed environment cannot change which routes or plugins were built. Static prerendered output retains the values from prerendering.

API Reference

See it on Pantry