# How to Integrate Logto with Your Application: A Complete Implementation Guide

> Learn how to integrate Logto with your application. This guide covers deploying Logto, configuring your app, and implementing OpenID Connect for seamless authentication.

- Repository: [Logto/logto](https://github.com/logto-io/logto)
- Tags: how-to-guide
- Published: 2026-07-06

---

**Integrate Logto with your application by deploying a Logto instance, creating an application in the Logto Console to obtain a Client ID, installing the appropriate framework SDK, and initializing the provider with your endpoint credentials to handle OpenID Connect authentication flows automatically.**

Logto is an open-source authentication platform that implements **OIDC**, **OAuth 2.1**, and **SAML** protocols, providing a complete identity infrastructure for web applications, mobile apps, and API services. When you integrate Logto, you interact with three core architectural components: the **Core server** (OIDC provider), **Connectors** (social/SMS providers), and **SDKs** (client-side libraries). This guide references the official `logto-io/logto` repository to walk you through the exact implementation steps and file locations needed to add secure authentication to your stack.

## Understanding Logto Architecture

Before writing integration code, understand how Logto’s components interact:

- **Core Server**: Located in [`packages/core/README.md`](https://github.com/logto-io/logto/blob/main/packages/core/README.md), this is the OIDC provider that handles token issuance, tenant management, RBAC, and the user database. It exposes the endpoints your SDK will call.

- **Connectors**: Found under `packages/connectors/`, these are micro-services that exchange OAuth codes or SMS tokens for Logto access tokens. For example, [`packages/connectors/connector-google/README.md`](https://github.com/logto-io/logto/blob/main/packages/connectors/connector-google/README.md) contains the implementation details for Google sign-in.

- **SDKs and UI Libraries**: The client-side wrappers live in [`packages/console/README.md`](https://github.com/logto-io/logto/blob/main/packages/console/README.md) (admin-console integration guides) and [`packages/elements/README.md`](https://github.com/logto-io/logto/blob/main/packages/elements/README.md) (UI components). These handle redirect logic, token storage, and automatic refresh.

## Step-by-Step Integration Process

### 1. Deploy a Logto Instance

Choose your deployment method based on your environment. The root [`README.md`](https://github.com/logto-io/logto/blob/main/README.md) contains quick-start commands for Docker Compose:

```bash
docker compose up -d

```

Alternatively, use the hosted **Logto Cloud** or spin up a GitPod demo for testing. Ensure your instance is accessible via HTTPS before configuring applications.

### 2. Create an Application in the Logto Console

Log in to your Logto Console and create a new application. Select the appropriate type:

- **SPA** (Single Page Application)
- **Traditional Web**
- **Native**
- **Machine-to-Machine**

The Console will generate a **Client ID** and (for confidential clients) a **Client Secret**. Store these securely; you will pass them to the SDK initialization.

### 3. Configure Social Connectors (Optional)

To enable social sign-in, add a connector such as Google. The configuration lives in [`packages/connectors/connector-google/README.md`](https://github.com/logto-io/logto/blob/main/packages/connectors/connector-google/README.md), which explains how to:

1. Create OAuth 2.0 credentials in the Google Cloud Console.
2. Paste the `clientId` and `clientSecret` into the Logto Connector settings.
3. Enable **Store tokens for persistent API access** if you need to call provider APIs (e.g., Google Drive) later; Logto will store these in its Secret Vault.

### 4. Add the Logto SDK to Your Application

Install the SDK matching your framework:

- React: `@logto/react`
- Next.js: `@logto/nextjs`
- Vue: `@logto/vue`

Initialize the provider with your endpoint and Client ID. The SDK automatically manages redirects to the Logto sign-in page and handles callback URLs.

### 5. Protect Routes and API Calls

Use the SDK’s hooks or HOCs to guard routes. Retrieve access tokens via `getAccessToken()` or `useAccessToken()` and attach them as `Authorization: Bearer` headers to your API requests.

## Code Implementation Examples

### React SPA Integration

Install the React SDK and wrap your application with `LogtoProvider`. The implementation references components from `packages/elements` and `packages/experience`.

```tsx
// src/index.tsx – initialise Logto
import { LogtoProvider } from '@logto/react';
import App from './App';

const endpoint = 'https://your-logto-instance.com';
const clientId = 'your-spa-client-id';

ReactDOM.render(
  <LogtoProvider endpoint={endpoint} clientId={clientId}>
    <App />
  </LogtoProvider>,
  document.getElementById('root')
);

```

Protect individual pages using the `useLogto` hook to check authentication status and fetch tokens:

```tsx
// src/App.tsx – protect a page
import { useLogto } from '@logto/react';
import { useEffect, useState } from 'react';

function Protected() {
  const { isAuthenticated, getAccessToken, signIn } = useLogto();
  const [profile, setProfile] = useState(null);

  useEffect(() => {
    if (isAuthenticated) {
      (async () => {
        const token = await getAccessToken();
        const res = await fetch('/api/me', {
          headers: { Authorization: `Bearer ${token}` },
        });
        setProfile(await res.json());
      })();
    }
  }, [isAuthenticated]);

  if (!isAuthenticated) return <button onClick={signIn}>Sign in</button>;
  return profile ? <pre>{JSON.stringify(profile, null, 2)}</pre> : <p>Loading…</p>;
}

```

### Next.js Integration

For server-side rendered applications, use `@logto/nextjs`. The provider wraps your [`_app.tsx`](https://github.com/logto-io/logto/blob/main/_app.tsx), while `withLogto` handles server-side token validation:

```tsx
// pages/_app.tsx – Logto wrapper
import { LogtoProvider } from '@logto/nextjs';
import type { AppProps } from 'next/app';

const endpoint = process.env.NEXT_PUBLIC_LOGTO_ENDPOINT!;
const clientId = process.env.NEXT_PUBLIC_LOGTO_CLIENT_ID!;

export default function MyApp({ Component, pageProps }: AppProps) {
  return (
    <LogtoProvider endpoint={endpoint} clientId={clientId}>
      <Component {...pageProps} />
    </LogtoProvider>
  );
}

```

Fetch the access token server-side using `getAccessToken` inside `getServerSideProps`:

```tsx
// pages/profile.tsx – server‑side token fetch
import { getAccessToken, withLogto } from '@logto/nextjs';

export const getServerSideProps = withLogto(async (ctx) => {
  const accessToken = await getAccessToken(ctx);
  const res = await fetch(`${process.env.LOGTO_API}/api/me`, {
    headers: { Authorization: `Bearer ${accessToken}` },
  });
  const profile = await res.json();

  return { props: { profile } };
});

export default function Profile({ profile }: { profile: any }) {
  return <pre>{JSON.stringify(profile, null, 2)}</pre>;
}

```

### Machine-to-Machine Authentication

For backend services communicating with protected APIs, use the `@logto/node` client (located in `packages/toolkit`) to execute the client-credentials flow:

```typescript
import { createClient } from '@logto/node';
import fetch from 'node-fetch';

const logto = createClient({
  endpoint: 'https://your-logto-instance.com',
  clientId: 'm2m-client-id',
  clientSecret: 'm2m-client-secret',
});

async function callProtectedApi() {
  const token = await logto.getAccessToken(); // obtains a machine token
  const res = await fetch('https://api.yourapp.com/secure-data', {
    headers: { Authorization: `Bearer ${token}` },
  });
  console.log(await res.json());
}

callProtectedApi();

```

The core token endpoint implementation is documented in [`packages/core/README.md`](https://github.com/logto-io/logto/blob/main/packages/core/README.md).

## Managing Federated Tokens

When you enable social connectors, Logto can persist provider tokens (Google, GitHub, etc.) in its **Secret Vault**. Retrieve these tokens via the secret-vault API to make authenticated calls to third-party services on behalf of the user. Configure this option in the connector settings within the Logto Console.

## Summary

- **Logto Architecture**: Consists of the Core server ([`packages/core/README.md`](https://github.com/logto-io/logto/blob/main/packages/core/README.md)), Connectors (`packages/connectors/`), and SDKs ([`packages/console/README.md`](https://github.com/logto-io/logto/blob/main/packages/console/README.md)).
- **Deployment**: Run via Docker Compose, Logto Cloud, or GitPod using commands from the root [`README.md`](https://github.com/logto-io/logto/blob/main/README.md).
- **Configuration**: Create an application in the Logto Console to get your **Client ID**, then optionally configure social connectors like Google.
- **SDK Integration**: Use framework-specific packages (`@logto/react`, `@logto/nextjs`, `@logto/node`) to initialize the provider and handle redirects.
- **Token Usage**: Retrieve access tokens via `getAccessToken()` or `useLogto()` hooks to secure API routes and external service calls.

## Frequently Asked Questions

### What authentication protocols does Logto support?

Logto implements **OpenID Connect (OIDC)**, **OAuth 2.1**, and **SAML** according to the architecture described in [`packages/core/README.md`](https://github.com/logto-io/logto/blob/main/packages/core/README.md). This allows integration with a wide range of identity providers and enterprise systems.

### Do I need to host my own Logto instance?

No. While you can self-host using Docker Compose (instructions in the root [`README.md`](https://github.com/logto-io/logto/blob/main/README.md)), Logto also offers a managed **Logto Cloud** service. Both options provide the same API surface and Console interface.

### How do I add social login providers like Google?

Add a connector from `packages/connectors/`. For Google specifically, follow the setup guide in [`packages/connectors/connector-google/README.md`](https://github.com/logto-io/logto/blob/main/packages/connectors/connector-google/README.md) to configure the OAuth client ID and secret. The connector micro-service will handle the token exchange with Google’s servers.

### Can I use Logto for machine-to-machine authentication?

Yes. Logto supports the **Client Credentials** flow for server-to-server authentication. Use the `@logto/node` SDK to create a client with your machine-to-machine credentials and call `getAccessToken()` to obtain bearer tokens for API access, as implemented in `packages/toolkit`.