docs/cli-docs/authentication.md

---
sidebar_position: 3
---

# Logging in

`gt auth login` logs in to a Gitea instance. gt can authenticate in three ways:

| Method | Flag | Best for |
| --- | --- | --- |
| OAuth in a web browser | `--oauth` | Interactive use, instances with single sign-on or two-factor authentication |
| Access token | `--with-token` | Any instance, machines without a browser |
| SSH key signing | `--ssh-key`, `--ssh-agent-key`, `--ssh-agent-principal` | Using an SSH key you already have instead of a token |

gt never asks for your password. On a terminal, `gt auth login` without a method flag asks
for the instance, how to log in, where to keep the token, and whether Git should use gt
for the instance:

```bash
gt auth login
```

## OAuth

```bash
gt auth login --host https://gitea.example.com --oauth
```

gt opens the instance's authorization page in your browser, or prints its URL when no
browser opens. You sign in there as you do on the web, so single sign-on through an
external identity provider and two-factor authentication work unchanged. gt listens on
`127.0.0.1` for the answer, so the browser has to run on the same machine as gt. OAuth
needs this interaction and is refused with `--no-input`.

By default the token has write access to everything but administration. `--scopes`
requests fewer, using the [token scope](/development/oauth2-provider#scopes) names:

```bash
gt auth login --host https://gitea.example.com --oauth --scopes read:repository,read:user
```

gt refreshes an expiring OAuth token on its own. `gt auth refresh` refreshes it now.

gt uses the OAuth application that Gitea registers by default for its command line
client, listed as `tea` in [`DEFAULT_APPLICATIONS`](/administration/config-cheat-sheet#oauth2-oauth2).
If an administrator turned it off, register an OAuth2 application that is not a
confidential client, with the redirect URI `http://127.0.0.1`, and pass its client ID with
`--client-id`. gt remembers the ID for the instance.

## Access tokens

1. Sign in to the instance in a web browser, with single sign-on or two-factor
   authentication if the instance uses them.
2. Under **Settings > Applications**, create an access token with the scopes you need.
3. Save the token in a private file and log in with it:

   ```bash
   gt auth login --host https://gitea.example.com --with-token < token.txt
   ```

   On a terminal, `--with-token` without input asks for the token instead.

gt needs `read:user` to find out which account a token belongs to. Add the scopes of the
commands you use:

| Scope | Commands |
| --- | --- |
| `repository` | `repo`, `pr`, `release`, `branch`, `run`, `workflow`, `secret` and `variable` of a repository, `webhook`, `wiki` |
| `issue` | `issue`, `label`, `milestone`, `time`, and comments on pull requests |
| `organization` | `org`, `team`, and `secret`, `variable` and `webhook` with `--org` |
| `notification` | `notification` |
| `package` | `package` |
| `user` | `ssh-key`, and `secret` and `variable` with `--account` |
| `admin` | `admin` |

Choose `write:` for the commands that change something, `read:` for the ones that only
read. Gitea counts pull request comments, labels and milestones as issue operations, so
working with pull requests usually needs both `write:repository` and `write:issue`. The
[scopes table](/development/oauth2-provider#scopes) describes each scope.

A token pasted with `--with-token` cannot be refreshed. When it expires or is revoked, log
in again.

## Where credentials are kept

gt keeps the instances and accounts in `hosts.yml` and its preferences in `config.yml`, in
its configuration directory. `gt config path` prints both files; `GITEA_CLI_CONFIG_DIR`
moves the directory.

Tokens are not written to these files. `--credential-store` chooses where they go:

- `keyring` (default): the system keyring, such as the macOS Keychain, the Windows
  Credential Manager, or the Secret Service on Linux. When no keyring is available, the
  login fails rather than falling back to a file.
- `file`: a `credentials` directory in the configuration directory that only your user
  can read. Use it where no keyring exists, such as in a container or over SSH.

A token given in `GITEA_TOKEN` is never stored. See [Using gt in CI](ci.md).

`gt auth status` shows the accounts on each instance, the active one, and how each
authenticates; `gt auth status --verify` checks every credential against its instance.
`gt auth token` prints the token of the active account, for scripts that call the API
themselves. `gt auth logout` forgets an account and deletes its stored credential.

## SSH keys

Instead of a token, gt can sign each API request with an SSH key that is registered for
your account on the instance:

```bash
gt auth login --host https://gitea.example.com --ssh-key ~/.ssh/id_ed25519
```

When a certificate (`id_ed25519-cert.pub`) is next to the key, gt signs with the
certificate. gt asks for the passphrase of an encrypted key. To sign with a key held by
`ssh-agent`, pass its fingerprint with `--ssh-agent-key`; to sign with an agent
certificate, pass its principal with `--ssh-agent-principal`. Accounts that sign requests
have no token, so `gt auth token` has nothing to print for them.

## Git over HTTPS

gt's own clone and checkout commands authenticate without any setup. For `git push` and
`git fetch` over HTTPS, let Git ask gt for credentials:

```bash
gt auth setup-git
gt auth setup-git --host gitea.example.com
# only for the current repository, always as alice
gt auth setup-git --local --user alice
```

Git then uses the active account of the instance, or the account of `--user`. Other
credential helpers, such as a system keychain, are turned off for the instance, since they
would answer first and keep a copy of gt's token; `--keep-helpers` keeps them.
`gt auth login` on a terminal offers to do this for you.

## Several instances and accounts

Run `gt auth login` once per instance and account. Commands pick the instance from the
repository's Git remote, `--host`, `GITEA_CLI_HOST`, the `default_host` setting, or the only
instance you are logged in to; `gt help environment` gives the full order.

Each instance has one active account. `gt auth switch` changes it: with two accounts it
toggles between them, with more it asks which one. `--user`, or `GITEA_CLI_USER`, uses
another account for a single command:

```bash
gt auth switch bob --host gitea.example.com
gt issue list --user alice
```

To use another instance by default outside a clone:

```bash
gt config set default_host https://gitea.example.com
```

## Access proxies and client certificates

An instance behind an access proxy may need extra headers or a TLS client certificate.
`--header` sends a header with every request to the instance; a value of `$NAME` or
`${NAME}` is read from that environment variable each time, so the secret stays out of
gt's files:

```bash
gt auth login --host https://gitea.example.com --with-token \
  --header 'CF-Access-Client-Id: $CF_ID' \
  --header 'CF-Access-Client-Secret: $CF_SECRET' < token.txt
```

`--client-cert` presents a PEM client certificate, and `--client-key` names its
unencrypted PEM key when the key is not in the certificate file. Convert a PKCS#12 file
with:

```bash
openssl pkcs12 -in cert.p12 -clcerts -nokeys -out cert.pem
openssl pkcs12 -in cert.p12 -nocerts -nodes -out key.pem
```

gt keeps these per instance; `gt config set headers`, `client_cert` and `client_key` with
`--host` change them later. `--insecure` skips TLS certificate verification for an
instance, for testing only.