Source: en/guide/quickstart.md · Live: https://docs.1pass.dev/en/guide/quickstart LLM-sanitized: internal links absolutized, VitePress containers → admonitions, line numbers in the Jump-to Index reference this rendered file (1-indexed).

📍 Jump-to Index

L32-L96: ## 🚀 Set up login in 5 minutes
- L77-L96: ### Finished registering? — the integration prompt
L97-L188: ## Doing it manually (CLI)
- L104-L139: ### 1. Log in (sign up first if you don't have an account)
- L140-L155: ### 2. Register the RP
- L156-L177: ### 3. Inject the secret env
- L178-L188: ### 4. Verify
L189-L197: ## Try asking it like this
L198-L205: ## Next steps
L206-L324: ## Manual integration (curl)
- L213-L216: ### Prerequisites
- L217-L227: ### Environment variables
- L228-L240: ### Generate a PKCE pair
- L241-L258: ### Get an Authorization Code
- L259-L298: ### Exchange for tokens
- L299-L318: ### Look up identity — two ways
- L319-L324: ### Manual integration troubleshooting

This single page connects logi login to your service (RP).

💡 Tip: Don't have an account yet? logi login is a login (not a sign-up). If you don't have a logi account, sign up first with the 1pass app or social sign-in (Apple/Google) — social accounts are created automatically on your first login. (App install: install)

There are only 3 things you do — the prompt below handles the rest.

Copy the prompt below into Claude Code · Cursor · Codex — replace only the <...> parts with your own values.
Approve the login once on your phone — if you signed up with email, also relay the 6-digit code sent to your inbox (Google · Apple sign-ups are automatic).
Inject the returned secrets into your deploy environment variables — never into code or git (they are shown only once).

When done you'll have everything needed to wire up login — 1 app ID + 2 secrets + an env block — and all that's left is to attach the button and callback following a framework guide.

text

If the logi CLI is missing, install it first: brew install dcode-co/logi/logi  (or gem install logi-cli)

Then run logi manual to load the manual into your context, and use the logi CLI to complete developer registration + RP registration end to end. (If the manual command is missing on an older CLI, read https://docs.1pass.dev/llms/guide/cli-rp-registration.md instead — Korean; no English edition yet.)

1. Run logi login to sign in (browser OAuth — I'll approve once on my phone). (If I don't have an account yet, sign up first with the 1pass app on my phone or social sign-in — SSO is created automatically.)
2. Run logi developer register --email <dev@example.com> --org "<My Company>" to gain developer privileges.
3. Run logi developer status to check identity_verified_level — if unverified, run logi developer verify-email and ask me for the 6-digit code from my email. (If I signed up via SSO it's already email_verified, so skip this step.)
4. Run logi apps create to register the RP:
   - --name "<My App>"
   - Pass exactly one byte-exact callback URL to --redirect-uri to create it, then if you need more callbacks (local / staging / prod / mobile scheme) add them one at a time with logi apps add-redirect <id> <uri>.
   - --scope openid profile:basic email   (valid scope names only — not bare profile, use profile:basic)
   - If there's a backend that can hide the secret use --client-type confidential; for mobile/SPA only use --client-type public. (Cannot be changed after creation, so choose carefully.)
5. Show me the client_id / client_secret / rp_health_secret and the env block from the create response. The secrets are shown only once, so never commit them to code/git — just tell me to put them into my deploy platform env.
6. Run logi apps verify <id> to validate the registration, and if it's pending because it's a production domain, tell me admin promotion is required.

A redirect_uri mismatch is the #1 OAuth incident, so be especially careful with step 5. If you get stuck, look up the topic in the index at https://docs.1pass.dev/llms.txt.

📖 Details: What this prompt does exactly — expand What you get — Users log in with a single approval in the logi app, and on your side you only attach the button and exchange the code for tokens at your callback, following a framework guide. Password storage, social connections, tokens, and security are all handled by logi.

What the AI does for you — Starting from checking the CLI install, it loads logi manual (self-describing manual; older-CLI fallback: the one-shot registration guide, LLM edition) to get facts like the host (api.1pass.dev) and scope (openid profile:basic email) right → developer registration → app registration → registration verification. When there's something to decide, like the callback URL or client type, the AI asks and you confirm.

The 3 values you receive — client_id (safe to expose) + client_secret · rp_health_secret (server-only, shown once). A mobile/SPA (public client) is issued without a client_secret.

💡 Tip: Full step-by-step + verification checklist The single source for this prompt is CLI step-by-step RP registration (one-shot guide) (Korean). Detailed explanations for each step, common sticking points, and a verification checklist that prevents false "done" reports are all there.

⚠️ Warning: Don't put internal infrastructure values in the prompt The prompt above uses only public CLI commands and public docs URLs. Don't put your secret values, deploy-platform tokens, or server access info into the prompt — when the AI produces the commands, inject the secrets into your own env store yourself.

Finished registering? — the integration prompt

Once you have a client_id from the registration prompt above, paste this next. The agent reads Quickstart for Agents (RP integration runbook) — track branching (mobile/web/api) + the F1-F8 pitfalls + anti-patterns — and writes the integration code.

text

Read https://docs.1pass.dev/llms-en/guide/agent-quickstart.md first, then add logi login to this project.

- client_id: <the value from registration>   (public value)
- issuer: https://api.1pass.dev
- redirect_uri: use the registered value byte-for-byte
- client_secret / rp_health_secret are already in the deploy env — never write them into code/git, reference them via env only.

Determine the track (mobile / web / api) first, then apply exactly one integration guide for that track.

💡 Tip: No secrets in this prompt either client_id is a public value, so it's safe to include in a prompt. This prompt assumes you've already finished step 3 above — injecting client_secret / rp_health_secret into your deploy env.

Doing it manually (CLI)

If you'll type the CLI commands by hand, follow the steps below. The managed IdP host is https://api.1pass.dev; for self-hosting see self-hosting.

💡 Tip: OAuth canonical host The issuer and discovery are fixed at https://api.1pass.dev: /.well-known/openid-configuration and /.well-known/jwks.json exist only here and return 404 on start.1pass.dev; the id_token's iss is also https://api.1pass.dev (not the brand name "logi"). start.1pass.dev is console-only. Some endpoints answer on both hosts, but standardize all RP endpoints on api.1pass.dev (matching the issuer).

Install the logi CLI in one line.

bash

brew install dcode-co/logi/logi
# or
gem install logi-cli

Install details / troubleshooting: logi CLI install.

If you don't have an account, sign up first with the 1pass app or SSO. logi login logs in to an existing account.

Log in — a browser opens and one approval on your phone finishes it. On a server/SSH/Docker with no browser, use logi login --code (device flow).

bash

logi login

Promote to developer privileges (needed to pass the RP registration gate).

bash

logi developer register --email dev@example.com --org "My Company"

Email verification — SSO (Google/Apple) sign-ups are auto-verified and skip this step. Only email/password sign-ups enter a code.

bash

logi developer status          # check identity_verified_level
logi developer verify-email    # if unverified — enter the 6-digit code from your email

ℹ️ Note: SSO sign-ups are auto-verified Google / Apple login accounts already have their email verified by the IdP, so identity_verified_level is automatically email_verified. Command details: developer registration (Korean).

2. Register the RP

bash

logi apps create \
  --name "My App" \
  --redirect-uri https://app.example.com/auth/logi/callback \
  --scope openid profile:basic email \
  --client-type confidential

redirect_uri must match byte-for-byte — --redirect-uri takes one at creation. If you need several (local / staging / prod / mobile scheme), create with one then add the rest with logi apps add-redirect <id> <uri> (redirect URI rules).
An RP that can't hide a secret (mobile/SPA) uses --client-type public (public vs confidential). Cannot be changed after registration.
If you'll use BCL, add --backchannel-logout-uri (Back-Channel Logout); for a mobile RP's backend health host use --health-url, and to disable the health check use --no-health-check (RP Active Health Check).

All options: app management commands. Registration policy (risk assessment · production promotion · rate limit): app registration guide.

3. Inject the secret env

The logi apps create output reveals 3 values in plaintext only at this moment.

client_id:        logi_...        ← safe to publish
client_secret:    logi_secret_... ← confidential only, once
rp_health_secret: logi_rphs_...   ← once, server env only

Put the env block printed alongside into your deploy platform's (Render / Vercel / Fly / Heroku / self-hosted) environment variables.

bash

LOGI_API_URL=https://api.1pass.dev
LOGI_CLIENT_ID=logi_...
LOGI_CLIENT_SECRET=logi_secret_...
LOGI_RP_HEALTH_SECRET=logi_rphs_...

🚨 Danger: Secrets are server-env only Never put LOGI_CLIENT_SECRET or LOGI_RP_HEALTH_SECRET into client code (mobile binary / SPA bundle / public git). client_secret and rp_health_secret appear in plaintext only in the create response, not in GET (list/show) — miss them and you'll need a secret rotation. A public client has no client_secret to begin with.

4. Verify

bash

logi apps verify <id>

It shows tier / status / rp_health_status / health_check_enabled. With only localhost redirects it's auto-approved (approved); if a production domain is included it's pending and needs admin review. To check directly whether the RP health endpoint actually responds, see self-diagnosis curl.

💡 Tip: Prevent false "done" — verification checklist A checklist that confirms CLI install · login · developer privilege · email verification · RP creation · 3 secrets obtained · env injection · verification green — one item at a time — is in the CLI one-shot guide · verification checklist (Korean).

Try asking it like this

Follow-up requests you can paste to your agent as-is after registration — just swap in your own client_id.

"Add logi login to this Next.js app. The client_id is logi_..., and the secrets are in the deploy env." → Next.js integration
"Wire up the Rails callback: exchange the code and verify the id_token." → Rails 8 integration
"Add logi login to the Flutter app, and register the custom scheme callback with logi apps add-redirect." → Flutter integration
"Build the endpoint that receives back-channel logout and verify the logout_token." → Back-Channel Logout

Next steps

Per-track code drop-ins: web Next.js · Rails 8 · Express / mobile iOS · Android · Flutter · React Native
Button components · Refresh rotation · Webhooks · Account Merge · Security
Agent runbook: Quickstart for Agents · CLI one-shot guide: cli-rp-registration (Korean)

Manual integration (curl)

The path that connects by calling the OAuth endpoints directly, without the CLI. After registering the RP via the CLI flow above (or in the console), you only need client_id / client_secret / redirect_uri.

💡 Tip: Endpoint discovery All endpoints are discovered at https://api.1pass.dev/.well-known/openid-configuration. start.1pass.dev returns 404 for discovery, so don't use it.

Prerequisites

bash, curl, openssl, python3.

Environment variables

bash

export LOGI="https://api.1pass.dev"
export CLIENT_ID="logi_..."
export CLIENT_SECRET="..."         # omit for a Public client
export REDIRECT="http://localhost:4000/auth/callback"

Use only valid scope names like openid profile:basic email — bare profile is rejected. Reading the id_token straight from the payload requires the openid scope; without it the token response omits the id_token (Scope reference).

Generate a PKCE pair

bash

VERIFIER=$(openssl rand -hex 32)

CHALLENGE=$(printf '%s' "$VERIFIER" \
  | openssl dgst -sha256 -binary \
  | python3 -c 'import sys,base64; print(base64.urlsafe_b64encode(sys.stdin.buffer.read()).rstrip(b"=").decode())')

echo "verifier  = $VERIFIER"
echo "challenge = $CHALLENGE"

Get an Authorization Code

bash

open "$LOGI/oauth/authorize?\
client_id=$CLIENT_ID&\
redirect_uri=$REDIRECT&\
response_type=code&\
scope=openid+profile:basic+email&\
state=random_xyz&\
code_challenge=$CHALLENGE&\
code_challenge_method=S256"

→ http://localhost:4000/auth/callback?code=...&state=random_xyz. Copy the code value.

💡 Tip: Show only specific login methods on the login screen If you want to surface only specific login methods — for example you use only Google Workspace company-wide — add a provider parameter to the authorize URL (e.g. &provider=google shows only the "Continue with Google" button). For the full behavior see login method restriction.

Exchange for tokens

bash

CODE="the_code_you_copied"

curl -s -X POST "$LOGI/oauth/token" \
  -d grant_type=authorization_code \
  -d code=$CODE \
  -d redirect_uri=$REDIRECT \
  -d code_verifier=$VERIFIER \
  -d client_id=$CLIENT_ID \
  -d client_secret=$CLIENT_SECRET

Public client: remove the -d client_secret=... line. Sending it triggers an invalid_client rejection.

bash

curl -s -X POST "$LOGI/oauth/token" \
  -d grant_type=authorization_code \
  -d code=$CODE \
  -d redirect_uri=$REDIRECT \
  -d code_verifier=$VERIFIER \
  -d client_id=$CLIENT_ID

Response:

json

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "DWxB...",
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9...",
  "scope": "openid profile:basic email"
}

The id_token is included only when you requested the openid scope.

Look up identity — two ways

Read sub from the id_token (no signature re-verification) — if you received the /oauth/token response directly over TLS, you can trust the sub in the id_token payload right away. Note the id_token carries only standard OIDC claims like sub — not email or name.

bash

echo "$ID_TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | python3 -m json.tool
# → {"iss":"https://api.1pass.dev","sub":"1","aud":"logi_...","exp":...,"iat":...,"at_hash":"..."}

💡 Tip: If received straight from the token endpoint, signature re-verification is optional An id_token received directly over TLS from /oauth/token within the same backend request can be trusted at the payload level (OIDC §3.1.3.7 #6 exception). Verifying the signature against JWKS is required only when the id_token arrives over an untrusted path (front-channel, stored and reused, or relayed). iss must be the literal "https://api.1pass.dev" and aud must equal CLIENT_ID. → JWKS verification

Get the profile (email, name) from userinfo — profile fields like email and name aren't in the id_token, so call userinfo with the access_token.

bash

ACCESS_TOKEN="access_token_from_the_response_above"
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" "$LOGI/oauth/userinfo"
# → {"sub":"1","nickname":"Gildong","name":"Hong Gildong","email":"user@example.com","email_verified":true}

Manual integration troubleshooting

invalid_client: a Public client sent a client_secret — remove the line.
PKCE: S256 is required, plain is rejected. redirect_uri allows only https / 127.0.0.1 / localhost / custom-scheme and must match the registered value byte-for-byte.
More detail: OAuth troubleshooting.

Quickstart — connect login in one pass ​

📍 Jump-to Index ​

Quickstart — connect login in one pass ​

🚀 Set up login in 5 minutes ​

Finished registering? — the integration prompt ​

Doing it manually (CLI) ​

1. Log in (sign up first if you don't have an account) ​

2. Register the RP ​

3. Inject the secret env ​

4. Verify ​

Try asking it like this ​

Next steps ​

Manual integration (curl) ​

Prerequisites ​

Environment variables ​

Generate a PKCE pair ​

Get an Authorization Code ​

Exchange for tokens ​

Look up identity — two ways ​

Manual integration troubleshooting ​

Quickstart — connect login in one pass

📍 Jump-to Index

Quickstart — connect login in one pass

🚀 Set up login in 5 minutes

Finished registering? — the integration prompt

Doing it manually (CLI)

1. Log in (sign up first if you don't have an account)

2. Register the RP

3. Inject the secret env

4. Verify

Try asking it like this

Next steps

Manual integration (curl)

Prerequisites

Environment variables

Generate a PKCE pair

Get an Authorization Code

Exchange for tokens

Look up identity — two ways

Manual integration troubleshooting