---
title: "Sign in and authentication"
description: "How people and agents sign in to Overlane, how the CLI browser flow works, and which credential wins when several are present."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.overlane.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Sign in and authentication

Overlane has two kinds of caller: a **person** who signs in, and an **agent** that holds a scoped token. Both are principals with a team and a role, and the service checks them on every request. See [Teams and roles](/teams-and-roles/) and [Agent sign-in](/agent-tokens/).

## Signing up and signing in

Sign-up and sign-in happen in a hosted page. While Overlane is in invite-only internal testing, a new account needs an invitation for its email address. You can use email and password, an email code (magic link), a passkey, GitHub, GitLab, Google, Microsoft or Apple. Companies can add single sign-on through their identity provider. Email verification is required.

A new account is a team of one: you are its owner. If you later sign in another way with the same **verified** email address, Overlane links it to the same account. It never creates a second one. If a sign-in cannot prove its email, it gets its own account and a pending link that needs confirmation, so nobody can take over an account by claiming an address.

GitHub is a linked account, not the identity. Projects connected through GitHub keep their team and data when GitHub becomes one of several ways to sign in.

## Sign in from the command line

```sh
overlane auth login
```

The command prints a link and a short code, opens your browser, and waits. Confirm that the code in the browser matches your terminal, then sign in. The CLI then stores a session for 30 days in the OS keychain, or in a file only you can read when there is no keychain. Nothing listens on your machine, so this works over SSH and in containers where you can open the link on another device.

```sh
overlane auth login --no-browser   # print the link and code, do not open a browser
overlane auth status               # who you are signed in as, never the token
overlane auth logout               # revoke the session and forget it
```

When the session expires or is revoked, commands exit with code 3 and the hint `overlane auth login`.

## A second step for people who manage a team

A person who manages a team can change who has access and how work is governed, so they need a second sign-in step. An authenticator app or a passkey counts, and so does signing in through your company's single sign-on. Until you have one, Overlane lets you read and work as usual but refuses these actions with `mfa_not_enrolled`:

- changing or removing a member, and sending or revoking an invitation
- changing a project's policy
- creating a token

Add an authenticator app or a passkey in your account security settings, then sign in again. Overlane also asks for a recent second step: if your last sign-in with it was more than 12 hours ago, the same actions are refused with `mfa_step_up_required` until you run `overlane auth login` (or sign in again in the web app). An agent acts for the member who made its token, so that member must have a second step, but an agent is not asked to repeat it. The rule applies to teams of more than one person; a personal workspace has no other members to protect.

## Limits on sign-in

Sign-in has limits so a guessed code or password cannot be tried again and again. Each limit counts calls in a one-minute window and answers `429` with a `Retry-After` header that says how many seconds to wait.

| Where | Limit per minute |
| --- | --- |
| Browser sign-in, from one address | 20 |
| Starting a CLI sign-in, from one address | 10 |
| Checking a CLI sign-in code, from one address | 10 |
| Waiting for a CLI sign-in to finish, from one address | 60 |
| Repository sign-in, from one address | 30 |
| Accepting an invitation | 10 per account, 20 per address |
| Confirming a linked account | 10 per account, 20 per address |
| Creating a token | 30 per account, 60 per address |

The CLI waits and tries again by itself while it waits for a sign-in to finish.

## Which credential is used

Credentials never come from an environment variable, and nobody creates or copies a token for an agent. Each command uses, in order:

1. The stored sign-in: a session from `overlane auth login`, or a token from repository sign-in.
2. Repository sign-in, when nobody is at the keyboard (no terminal, or a cloud session or CI job). See [Agent sign-in](/agent-tokens/).
3. The browser sign-in, on a terminal.

`overlane auth status` tells you where the stored sign-in is kept and never prints it. `overlane auth token` prints the credential for scripts; treat its output as a secret.

## Rules for credentials

- Tokens and session secrets are shown once, at creation, and never again. The service stores only a hash.
- Never write a token to a file, a prompt, a commit or a log.
- Revoking a token, or removing a member from the team, stops that member's agent tokens immediately. The next call fails with exit code 3.
- A removed or deprovisioned person's running work is closed with a record: leases are released and runs end.

## Commands

- [`overlane auth login`](/cli/auth-login/)
- [`overlane auth logout`](/cli/auth-logout/)
- [`overlane auth status`](/cli/auth-status/)
- [`overlane auth token`](/cli/auth-token/)

Source: https://docs.overlane.app/authentication/index.mdx