---
title: "Agent sign-in and agent tokens"
description: "How agents sign in from the CLI, with a device code approved on any device or with repository sign-in for unattended runs, and how agent tokens end."
---

> 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.

# Agent sign-in and agent tokens

Agents sign in from the CLI. Nobody creates, copies or pastes agent tokens, and there is no screen or command to make one by hand.

## With a person watching: a device code

```sh
overlane auth login
```

The CLI prints a link and a short code. Open the link on any device (a phone is fine), check that the code matches and sign in. The CLI stores a 30-day session in the OS keychain, or in a file readable by your account alone. In a cloud session, the agent runs the command and you tap the link.

## Unattended: repository sign-in

Cloud sessions, routines, scheduled jobs and CI sign in for the repository they have checked out:

```sh
overlane auth login --repo
```

Every other command does the same on its own when there is no terminal, so a scheduled run needs no setup step. What it takes:

- The repository is connected to an Overlane project through the Overlane GitHub App, either as the project's repository or as the GitHub side of an Overlane repository's mirror. Installing the App and connecting or mirroring the repository is the whole setup.
- The run can push to that repository. Where the platform gives the job an identity token (GitHub Actions with `id-token: write`), that token is exchanged directly. Everywhere else the CLI pushes an empty commit that names a one-time challenge to `refs/overlane/proof/<id>`, or to a branch ending in `overlane-proof-<id>` where only branches can be pushed. The service reads it through the App, deletes it, and checks a secret only the CLI holds, so reading the pushed commit is not enough to sign in. Where a sandbox lets the run push only its own working branch (Claude Code on the web does), the CLI puts the proof commit on top of that branch, with the same files, and moves the branch back as soon as the service has read it. It never does this on `main`.
- The CLI never reads or sends the sandbox's own git credentials.

The token it gets:

- is for that one project, with the agent role: it is refused on any other project and on team-level routes;
- lasts one hour and cannot be refreshed: the CLI signs in again when it expires;
- cannot mint other tokens;
- acts for the team member who installed the App, and stops working if that member leaves the team.

Jobs started by pull requests, comments or other workflows' runs cannot sign in this way, since they can run code from people without write access. A repository that is not connected gets the same answer as one that does not exist, so the route does not reveal which repositories use Overlane. Challenges are limited per repository and per address.

## List and revoke

```sh
overlane token list
overlane token revoke tok_abc123 --force
```

Revocation is immediate: the next call with the token fails with `401 token_revoked` and the CLI exits with code 3. Removing the member a token acts for, uninstalling or suspending the GitHub App, or disconnecting the repository ends the tokens repository sign-in made.

## Errors

| Situation | HTTP | Exit code |
| --- | --- | --- |
| Unknown token | 401 `unauthorized` | 3 |
| Revoked token | 401 `token_revoked` | 3 |
| Expired token | 401 `token_expired` | 3 |
| Repository not connected through the GitHub App | 403 `repository_not_connected` | 3 |
| A person asks the API for an agent token | 403 `cli_sign_in_only` | 6 |
| Role or scope does not allow it | 403 `forbidden` | 6 |
| A token from repository sign-in tries to mint another | 403 `token_depth` | 6 |
| Too many sign-in attempts for a repository | 429 `rate_limited` | 1 |

## Commands

- [`overlane auth login`](/cli/auth-login/)
- [`overlane token list`](/cli/token-list/)
- [`overlane token revoke`](/cli/token-revoke/)

Source: https://docs.overlane.app/agent-tokens/index.mdx