How to Integrate Logto with Vue.js Applications: A Complete Implementation Guide

To integrate Logto with Vue.js, install the @logto/vue SDK, initialize the plugin with your endpoint and appId in main.ts, create a callback route using useHandleSignInCallback, and manage authentication state with the useLogto composable.

Logto is an open-source OpenID Connect (OIDC) provider that streamlines identity management for modern web applications. According to the official source code in packages/console/src/assets/docs/guides/spa-vue/README.mdx, the @logto/vue SDK leverages Vue 3's Composition API to provide reactive authentication primitives. This guide walks through the complete integration process, from installation to implementing production-ready sign-in flows.

Prerequisites and Installation

Vue 3 Requirement

The @logto/vue SDK is built exclusively for Vue 3 using the Composition API. Verify your project uses Vue 3 before proceeding, as the SDK does not support Vue 2's Options API.

Installing the SDK

Add the Logto Vue SDK to your project via npm:

npm install @logto/vue

Initializing the Logto Client

In your main.ts entry file, import createLogto from @logto/vue and register it as a Vue plugin. The configuration requires your Logto endpoint and appId, obtained from the Logto Console when creating a Single Page Application (SPA).

import { createLogto, type LogtoConfig } from '@logto/vue';
import { createApp } from 'vue';
import App from './App.vue';

const config: LogtoConfig = {
  endpoint: 'https://your-logto-instance.com',
  appId: 'your-app-id',
};

const app = createApp(App);
app.use(createLogto, config);
app.mount('#app');

This initialization follows standard Vue 3 plugin architecture, injecting the Logto client throughout your application's component tree.

Configuring the Callback Route

Router Setup

After authentication, Logto redirects users to a specified callback URL. Define this route without authentication guards to allow the OIDC flow to complete. As shown in packages/console/src/assets/docs/guides/spa-vue/README.mdx#L65-L92, implement a dedicated /callback route:

import { createRouter, createWebHistory } from 'vue-router';
import CallbackView from '@/views/CallbackView.vue';
import HomeView from '@/views/HomeView.vue';

const router = createRouter({
  history: createWebHistory(),
  routes: [
    { path: '/', name: 'home', component: HomeView },
    {
      path: '/callback',
      name: 'callback',
      component: CallbackView, // No auth guard needed
    },
  ],
});
export default router;

Handling the Redirect

In your CallbackView.vue component, use the useHandleSignInCallback composable to process the authorization code exchange. This function handles token retrieval and executes your callback upon completion:

import { useHandleSignInCallback } from '@logto/vue';
import router from '@/router';

export default {
  setup() {
    const { isLoading } = useHandleSignInCallback(() => {
      // Navigate home after successful authentication
      router.push({ name: 'home' });
    });
    return { isLoading };
  },
};

<template>
  <p v-if="isLoading">Redirecting…</p>
</template>

The isLoading reactive state indicates while the SDK processes tokens, preventing premature navigation.

Implementing Authentication UI

Use the useLogto() composable to access authentication methods and state throughout your application. This exposes signIn, signOut, isAuthenticated, and getIdTokenClaims for full session management.

Sign-In and Sign-Out Buttons

Implement the user interface in HomeView.vue or protected components:

import { useLogto, type IdTokenClaims } from '@logto/vue';
import { ref } from 'vue';

export default {
  setup() {
    const { signIn, signOut, isAuthenticated, getIdTokenClaims } = useLogto();
    const user = ref<IdTokenClaims>();

    if (isAuthenticated.value) {
      (async () => {
        user.value = await getIdTokenClaims();
      })();
    }

    return { signIn, signOut, isAuthenticated, user };
  },
};

<template>
  <div v-if="isAuthenticated && user">
    <button @click="signOut()">Sign out</button>
    <table class="table">
      <thead>
        <tr><th>Claim</th><th>Value</th></tr>
      </thead>
      <tbody>
        <tr v-for="(value, key) in user" :key="key">
          <td>{{ key }}</td>
          <td>{{ typeof value === 'string' ? value : JSON.stringify(value) }}</td>
        </tr>
      </tbody>
    </table>
  </div>
  <div v-else>
    <button @click="signIn('http://localhost:5173/callback')">Sign in</button>
  </div>
</template>

The signIn method requires your callback URL as a parameter, which must match the redirect URI configured in your Logto Console application settings.

Architecture and Security Considerations

The Vue SDK wraps Logto's core JavaScript client with Vue-specific reactivity patterns. State persistence occurs in memory with localStorage backup, ensuring sessions survive page reloads. All OIDC communication uses HTTPS, and the SDK requires only the public appId—client secrets never expose in browser environments.

The architectural separation between useHandleSignInCallback (flow completion) and useLogto (state management) maintains clean concerns. Because the SDK follows standard OIDC protocols, you can replace default UI components while retaining the same composables for authentication logic.

Summary

• Install @logto/vue via npm to add OIDC authentication to Vue 3 projects using the Composition API.
• Initialize in main.ts using createLogto with your endpoint and appId configuration.
• Create a callback route at /callback using useHandleSignInCallback to complete the OIDC flow without authentication guards.
• Access auth state via the useLogto composable, exposing signIn, signOut, isAuthenticated, and getIdTokenClaims.
• Reference the source in packages/console/src/assets/docs/guides/spa-vue/README.mdx for authoritative implementation details maintained by the logto-io/logto repository.

Frequently Asked Questions

Does Logto support Vue 2 or only Vue 3?

The @logto/vue SDK exclusively supports Vue 3 and its Composition API. Vue 2 applications must either migrate to Vue 3 or integrate the underlying @logto/browser SDK with custom Vue 2 composition logic.

Where is the authentication state stored?

The SDK maintains authentication data in memory and persists it to localStorage for session continuity across page reloads. This hybrid approach balances reactivity with persistence requirements.

Why must the callback route remain unprotected?

The callback route processes the OIDC authorization code exchange before tokens are available. Authentication guards would block the completion of the sign-in flow, as the user remains unauthenticated until useHandleSignInCallback finishes processing the redirect.

Can I customize the post-sign-in redirect behavior?

Yes. The useHandleSignInCallback composable accepts a callback function executed after successful token exchange. You can navigate to specific routes, update Pinia stores, or trigger additional initialization logic within this callback.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}