---
sidebar_position: 3
---

# Logging in

On a terminal, `gt auth login` asks for the instance and how to log in. gt never asks for
your password.

## OAuth in a browser

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

gt opens the instance's authorization page, so single sign-on and two-factor
authentication work as on the web. The browser has to run on the same machine as gt.
`--scopes` limits the token to fewer [scopes](/development/oauth2-provider#scopes); gt
refreshes OAuth tokens on its own.

## Access token

Create a token under **Settings > Applications** on the instance and pass it on stdin:

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

The token needs `read:user`, and the scopes of what you do with gt, such as
`write:repository` and `write:issue` for working on pull requests.

## SSH key

gt can sign its requests with an SSH key registered for your account instead of using a
token:

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

## Where credentials are kept

Tokens go to the system keyring by default. `--credential-store file` keeps them in gt's
configuration directory instead, for machines without a keyring. `gt auth status` lists
your accounts and `gt auth logout` removes one.

## Git over HTTPS

`gt auth setup-git` lets `git push` and `git fetch` over HTTPS use gt's login. gt's own
clone and checkout commands need no setup.

## Several instances and accounts

Run `gt auth login` for each instance and account. gt picks the instance from the
repository's remote or `--host`, and the account with `gt auth switch` or `--user`.
For instances behind an access proxy, `--header` and `--client-cert` add headers and a
client certificate; see `gt auth login --help`.