How to Use Logto: The Beginner's Guide (First Deploy, First Application, the SDK Lesson, and the RBAC Lane)

CodexFuse Team · 2026-11-01T13:51:45.300Z · 18 min read

Learn how to use Logto: self-host v1.45.0 with Docker, create your first application, add React sign-in, connect social logins, and set up RBAC.

Learning how to use Logto is the fastest way for a developer or small team to get Auth0-style authentication — sign-up, sign-in, social login, and API authorization — running on infrastructure they actually own. Logto is an open-source identity and access-management platform, billed by its makers as the Auth0 alternative you can self-host, and this logto tutorial walks the whole beginner arc in one place: deploy it with Docker, tour the Admin Console, register your first application, wire sign-in into a React app, add social connectors, protect an API with RBAC, and drive users through the Management API.

One naming note so you do not land on the wrong product: the identity platform in this guide is Logto at logto.io — not the legacy LOGTO terminal command from NEC's Reality database system, which owns some confusing search results for the bare word "logto". Everything below is about the open-source auth platform.

You have two entry points, and every arc below works on both: start a free Logto Cloud tenant and reach a working sign-in in minutes, or self-host Logto on your own server with Docker for full data control. The self-hosted route assumes you are comfortable with containers — our Docker beginner guide covers the compose basics this guide builds on. If you are surveying the self-hosted identity world first, our Authentik beginner guide covers the sibling lane: Authentik is the do-it-yourself identity-provider server, while Logto is the developer auth platform in the Auth0 mold — different lanes, never rivals.

What Is Logto?

Logto is an open-source customer identity and access management platform that gives your app sign-up and sign-in flows, social and enterprise login, multi-factor authentication, role-based access control, and organization (multi-tenant) support — built on OpenID Connect and OAuth 2.1, and deployable on your own infrastructure or as a managed cloud.

The project lives at github.com/logto-io/logto under the MPL-2.0 license. At the time of writing it has about 14,800 stars and 1,200 forks, and the current stable release is v1.45.0, released October 13, 2026, which added license-based premium entitlements for self-hosted Pro. Those figures come from the project's GitHub repository and releases page, fetched today.

Here is the one mental-model lesson that makes the whole product click: Logto is the identity service, and it has three faces. The Admin Console is where you configure everything, the SDKs are how your app talks to it for sign-in, and the Management API is how your backend manages users, roles, and organizations programmatically. Once you see those three faces, every screen in the product makes sense.

Logto vs Authentik: Which One Do You Actually Need?

You need Logto when you want Auth0-style developer auth — SDKs, API resources, RBAC, and a pricing model that scales with tokens instead of users — and you need Authentik when you want a self-hosted single-sign-on server that glues your homelab services together behind one login. The honest line, said once: Authentik is the DIY identity provider you operate; Logto is the auth platform you integrate.

Concretely: if your project is "add Google/GitHub login plus roles to my SaaS", Logto's application model, SDK quickstarts, and Management API fit directly. If your project is "one login for my NAS, Proxmox, and twenty Docker apps", Authentik's provider model fits better. Many teams run both — Logto for their product's users, Authentik for their own infrastructure — and they are never rivals for the same job.

How Do You Deploy Logto with Docker?

Deploying logto self hosted takes one command for the demo setup, and the official path is a Docker Compose file with two services: the Logto app and a Postgres database. Self-hosted Logto needs Postgres — it is the only supported database, so plan for Postgres 14 or newer from the start.

The official one-liner, from the Logto OSS get-started docs, is:

curl -fsSL https://raw.githubusercontent.com/logto-io/logto/HEAD/docker-compose.yml | docker compose -p logto -f - up

That command is demo-only, not for production: the bundled Postgres uses an anonymous volume, so re-running the compose file loses your data. For anything real, download the compose file, point DB_URL at a persistent Postgres, and pin the image tag. This logto docker walkthrough sticks to the official compose file so every step matches the vendor's own layout.

The compose shape is worth understanding because it teaches the architecture. Two services run: app (Logto itself) and postgres (postgres:17-alpine, healthchecked, with the app waiting until the database is healthy). Two ports are published, and this is the number-one first-deploy confusion, so learn it once: port 3001 is the core service — the auth endpoint your apps and SDKs talk to — and port 3002 is the Admin Console, the web UI you configure everything in. The documented minimum hardware is 2 vCPU, 8 GiB of RAM, and 256 GiB of disk.

One honest flag on the image name: the official upgrade guide pins ghcr.io/logto-io/logto:1.45.0 and explicitly recommends an exact version tag over latest, but the repo's own demo compose file currently points at a different svhd/logto image. Pin the docs' ghcr.io/logto-io/logto:1.45.0 tag — exact versions are what the vendor itself recommends, and they make upgrades predictable.

What Happens on Your First Launch?

Your first launch ends at the Admin Console welcome page, where you create the single admin account that owns the instance. Open http://localhost:3002/ after the compose stack is up, and the welcome page offers exactly one admin account creation: a username and a password of at least 8 characters, checked against the HaveIBeenPwned breached-password list. After that, registration on the admin tenant closes — there is no public sign-up page sitting open on your server.

The open-source edition supports a single console admin. Adding more console members requires a self-hosted Pro license (Tenant Settings, then Members) — one of the premium entitlements the v1.45.0 release introduced. For a solo developer or small team starting out, the single admin is all you need.

How Do You Create Your First Application?

Creating your first application takes about a minute, and it starts in the Console under Applications with the "Create application" button. Logto asks you to pick one of four application types first, and the choice matters because it decides whether your app gets a secret:

Pick the type or a framework card (for example "React"), name the application, and click Create. Logto shows a congrats page with a tailored integration guide — the same steps this article covers below, customized to your framework.

Then comes the redirect-URI lesson, and it is load-bearing: on the application details page, add the exact redirect URI your app will use, such as http://localhost:3000/callback. Logto defines the redirect URI as the address it sends users back to after they finish signing in on the Logto page — and it must match, character for character, what your app sends in the sign-in request. A trailing slash you forgot is the classic hour-long debugging session. Also set a post sign-out redirect URI (for example http://localhost:3000/) so signed-out users land somewhere sensible. Since v1.36, wildcard redirect-URI patterns are supported for preview deployments, which saves you from registering a new URI for every pull-request environment.

How Do You Add Sign-In to a React App?

Adding sign-in to a React app is a seven-step arc, and it is the heart of this logto react guide — the SDK does the OAuth dance so you only write the wiring:

1. Install the SDK in your own React project: npm i @logto/react. The official quickstart integrates into your project; a sample project on the SDK's GitHub repo is linked as reference.
2. Build the config with your two values — the auth endpoint and the application ID from the Console: { endpoint: 'http://localhost:3001', appId: '<your-application-id>' }. Note the endpoint is port 3001, the core service, not the 3002 console.
3. Wrap your app in <LogtoProvider config={config}> so every component can reach the Logto client.
4. Call signIn('http://localhost:3000/callback') from a button, using the useLogto() hook: const { signIn, signOut, isAuthenticated } = useLogto();. Sign-out is signOut(), which clears the stored Logto data.
5. Create a Callback page with useHandleSignInCallback(() => { /* redirect home */ }) and mount it on a /callback route that does NOT require authentication — the SDK needs to land there unauthenticated to finish the exchange.
6. Read the signed-in user with getIdTokenClaims() for profile data. The SDK always requests the openid, profile, and offline_access scopes; extra claims come from the config's scopes option.
7. Test the full loop: click sign-in, complete the Logto-hosted sign-in page, land back on your callback route, and confirm isAuthenticated is true.

That arc follows the current React quickstart in the Logto docs, verified at write time. The sign-in page your users see is hosted by Logto and customizable from the Console's Sign-in Experience section — you do not build login UI yourself.

How Do Social Connectors Work?

Social connectors live in the Console under Connectors, then Social Connectors, and they turn "sign in with GitHub" into a configuration task instead of an OAuth implementation. The setup shape is the same for every provider: create the OAuth app on the provider's side, paste its Client ID and Client Secret into the connector's fields in Logto (plus scopes — Facebook defaults to email and public_profile), and register the callback URI Logto gives you at the provider.

The built-in catalog, from the docs integrations page, is broad: Google, Facebook, Apple, Microsoft, GitHub (both OAuth App and GitHub App flavors), Discord, Amazon, Alipay, DingTalk, Feishu, GitLab, Hugging Face, Kakao, and KOOK — plus generic OAuth 2.0 and OIDC connectors for anything not listed. If your app's audience lives on GitHub, our GitHub beginner guide covers the platform side — creating the OAuth app whose credentials you paste into Logto's GitHub connector.

What Is Logto RBAC, and How Do API Resources Work?

Logto RBAC answers the question every app hits after login works: "this user is signed in — but what are they allowed to do?" The model has three pieces, and Logto's docs treat the words "scopes" and "permissions" as interchangeable, so do not let the two terms confuse you.

An API resource is the backend service you want to protect, identified by a URI — Logto follows RFC 8707, so the identifier must be an absolute URI like https://api.example.com, and access tokens are audience-restricted to it. A permission (scope) is one allowed action, like read:report or invite:member. A role is a bundle of permissions, like admin or viewer. The flow: register the API resource and its permissions in Logto, assign permissions to roles, assign roles to users or clients, then request access tokens with the resource parameter matching your API's identifier.

Access tokens are signed JWTs carrying three things your API checks: aud (which API this token is for), scope (the space-separated permissions), and organization_id when the token is org-scoped. Two facts beginners get wrong: permission changes appear only in newly issued tokens — existing tokens keep their old scopes until they expire — and your API validates the token by checking the signature against Logto's JWKS at https://<your-logto-endpoint>/oidc/jwks, plus issuer, audience, expiration, and scopes.

The proxy-side use case is worth one line: our Pomerium beginner guide covers the identity-aware proxy that consumes an IdP over OIDC — Logto can be that IdP, so the RBAC you configure here becomes the identity layer Pomerium enforces per request.

What Does the Logto Management API Unlock?

The Management API is Logto's third face: everything the Console does, your backend can do over HTTP. The base path is your Logto endpoint plus /api — for example GET https://[tenant-id].logto.app/api/users with a Bearer token lists the first page of users. User provisioning, role assignment, organization management, and connector configuration all live here.

Getting a token is a three-step machine-to-machine flow, from the official authentication docs:

1. Create a machine-to-machine application in the Console.
2. Create an M2M role holding the Management API permission all, and assign it to that application.
3. POST to <tenant>/oidc/token with grant_type=client_credentials, your client ID and secret, resource=https://[tenant-id].logto.app/api, and scope=all. The response is a Bearer token valid for 3600 seconds.

Then it is plain REST: list users with curl -H "Authorization: Bearer <token>" https://[tenant-id].logto.app/api/users, create users, assign roles, and manage organizations — the whole user lifecycle without opening the Console.

How Does Logto Enterprise SSO Work?

Logto's logto sso story is called Enterprise SSO, and it lives in the Console under its own Enterprise SSO section. The idea is domain-based routing: you add an enterprise connector for a customer's identity provider, bind their email domain, and every user signing in with that domain is sent to their IdP — with JIT provisioning adding them as organization members on first login, and automatic account linking for existing same-domain users.

The pre-built connectors cover the three providers B2B buyers ask about first: Google Workspace, Microsoft Entra ID, and Okta. Anything else connects through a custom SAML or OIDC connector. On Cloud plans, Enterprise SSO is a paid add-on — which brings us to the money question.

Logto vs Auth0: How Do They Compare?

Logto positions itself against Auth0 on three axes, and its own comparison page states them plainly enough to quote: no MAU growth tax and no forced feature bundling, token-based pricing where only issued access tokens count ("if a user doesn't log in, you don't pay"), an open-source core with a built-in exit strategy to self-hosting, and modular B2B add-ons instead of bundled tiers. The deployment contrast is the sharpest line: Logto runs as cloud, private cloud, or self-hosted, while Auth0 is cloud-only.

One honesty note on that table: it summarizes Logto's own comparison page, fetched today — it is the vendor's framing, not an independent audit. Verify Auth0's current pricing yourself before deciding; the structural points (token pricing, self-hosting, open core) are the durable ones.

Logto Cloud or Self-Hosted: Which Should You Pick?

Start on Logto Cloud's free tenant to learn, and self-host when you want the data on your own Postgres — that is the whole graduation line, said once. The Cloud pricing, fetched from logto.io/pricing today: Free costs $0 a month with no credit card, up to 50,000 monthly active users and 50,000 tokens, covering user authentication, a machine-to-machine app, account APIs, audit logs, and user management. Pro starts at $24 a month with 50,000 free tokens and then usage billing, unlimited MAU and applications, and the B2B features as separate add-ons — RBAC, Organizations, MFA, Enterprise SSO at $48, SAML apps at $96, and OIDC/OAuth third-party apps at $8. Enterprise is contact-sales.

Self-hosting the open-source edition is free; premium self-hosted features unlock with a Self-Hosted Pro license, the entitlement model v1.45.0 introduced. The demo compose file gets you learning in minutes, but production needs a real Postgres with persistent storage, a pinned image tag, HTTPS in front of both ports, and backups of the database — the same production checklist as any stateful service.

Seven Beginner Mistakes to Avoid

Every one of these has bitten a real first deploy. They are all avoidable once you have seen them:

Sources

Every fact above was verified from a page fetched today, 2026-11-01: the Logto OSS get-started guide and CLI docs (docs.logto.io/logto-oss — compose file, Postgres requirement, seed command, first-launch admin flow, minimum hardware), the OSS version-upgrade guide (image pinning), the raw docker-compose.yml from the logto-io/logto repository, the GitHub repository and releases page for logto-io/logto (stars, forks, MPL-2.0 license, v1.45.0 release date), the Logto changelog blog, the React quickstart (docs.logto.io/quick-starts/react — SDK package, config shape, sign-in flow, callback route, scopes), the application data-structure and authentication-flow docs (four app types, redirect-URI behavior, wildcard URIs in v1.36), the authorization docs (API resources, RBAC terminology, token contents, JWKS and discovery endpoints), the Management API authentication docs on openapi.logto.io (M2M token flow, /api/users), the integrations page and social-connector tutorials (built-in connector list, client ID/secret setup), the Enterprise SSO docs (pre-built connectors, domain routing, JIT provisioning), logto.io/pricing (Free and Pro tiers, add-on prices), and logto.io/compare/auth0 (the Auth0 positioning summary, flagged as vendor framing). The Hasura and Encore Logto integration guides and the dev.to Logto API walkthrough corroborated the self-host ports and endpoint layout.

Frequently Asked Questions

Is Logto really free?

Self-hosting the open-source edition is free under the MPL-2.0 license — you pay only for your own server. Logto Cloud's Free tier is $0 a month with no credit card: up to 50,000 monthly active users and 50,000 tokens. Premium features (RBAC, Organizations, MFA, Enterprise SSO, SAML apps) are paid add-ons on Cloud, or unlock on self-hosted via a Self-Hosted Pro license.

Do I need a database to self-host Logto?

Yes — Postgres is mandatory and the only supported database (version 14 or newer). The official compose file bundles Postgres 17 for the demo, but production needs a persistent Postgres you manage, with the DB_URL connection string pointed at it and the database seeded via the Logto CLI.

Should I pick Logto or Authentik?

Pick Logto when you are building a product and want Auth0-style developer auth — SDKs, API resources, RBAC, token-based pricing. Pick Authentik when you want a self-hosted single-sign-on server gluing your own infrastructure together. They solve different problems; many setups run both.

Can Logto replace Auth0?

That is exactly the migration Logto is built for: OIDC/OAuth 2.1 standards, SDKs for the same frameworks, and a pricing model that charges per issued token instead of per active user. The open-source core also gives you an exit strategy Auth0 cannot — move the same system to your own servers. Compare current Auth0 pricing yourself before deciding.

Is this the same "logto" as the database command?

No. The LOGTO command belongs to NEC's legacy Reality database system and has nothing to do with identity management. If a search result talks about TCL commands, accounts, and logon procs, you have found the database homonym — this guide covers only the Logto identity platform at logto.io.