g1t/apps/docs/src/content/docs/guides/authentication.md
| 1 | --- |
| 2 | title: Accounts and authentication |
| 3 | description: Accounts, email confirmation, personal access tokens, OAuth, signing in from a tool, and password reset. |
| 4 | --- |
| 5 | |
| 6 | ## Creating an account |
| 7 | |
| 8 | Register at [g1t.sh/register](https://g1t.sh/register). Usernames are |
| 9 | lowercase letters, digits and single hyphens, up to 39 characters. |
| 10 | |
| 11 | Accounts can only be created in a browser. There is no API for it, by |
| 12 | design: it keeps passwords out of scripts and agents, and lets g1t protect |
| 13 | the one place accounts are made. |
| 14 | |
| 15 | ## Confirming your email |
| 16 | |
| 17 | g1t sends a confirmation link from `noreply@g1t.sh`. It works for 24 hours. |
| 18 | |
| 19 | Until you follow it you can sign in and look around, but you cannot create |
| 20 | repositories, push, or open issues and pull requests. Those requests fail with `403` and a |
| 21 | message telling you to confirm your address. To get a new link, sign in and |
| 22 | use the banner at the top of the site. |
| 23 | |
| 24 | ## Workspaces |
| 25 | |
| 26 | Your account does not own repositories itself: a workspace does. After |
| 27 | confirming your email, the first thing you do is create one. Workspaces, |
| 28 | their members and roles, and the access tokens that belong to a workspace |
| 29 | are covered in [workspaces](/guides/workspaces/). |
| 30 | |
| 31 | ## Access tokens |
| 32 | |
| 33 | A token stands in for your password everywhere outside the website: |
| 34 | |
| 35 | | Where | How to send it | |
| 36 | | --- | --- | |
| 37 | | git | As the password, with your username. | |
| 38 | | API | `Authorization: Bearer g1t_…` | |
| 39 | | MCP | The same header, set when you add the server. | |
| 40 | |
| 41 | Create one in [Settings](https://g1t.sh/settings). A token is shown once, |
| 42 | when it is created; g1t stores only a hash of it. If you lose one, delete it |
| 43 | and create another. Delete a token the moment you think someone else has |
| 44 | seen it. |
| 45 | |
| 46 | A token has the full rights of your account. Scoped tokens are planned. |
| 47 | |
| 48 | For CI and integrations that work for a team, a workspace can have tokens |
| 49 | of its own that act as the workspace and keep working when their creator |
| 50 | leaves. See [workspace access tokens](/guides/workspaces/#workspace-access-tokens). |
| 51 | |
| 52 | ## Signing in with OAuth |
| 53 | |
| 54 | Applications that can open your browser, such as an agent connecting to the |
| 55 | [MCP server](/guides/bring-your-own-agent/), sign you in with OAuth 2.1. |
| 56 | You see a page on g1t naming the application and where it will send you |
| 57 | back, and you approve or deny. The application never sees your password and |
| 58 | there is no token to copy. |
| 59 | |
| 60 | Applications you have approved are listed under **Connected applications** |
| 61 | in [Settings](https://g1t.sh/settings). Signing one out ends its access at |
| 62 | once. |
| 63 | |
| 64 | For people building a client: |
| 65 | |
| 66 | | | | |
| 67 | | --- | --- | |
| 68 | | Metadata | `https://api.g1t.sh/.well-known/oauth-authorization-server` | |
| 69 | | Authorization | `https://g1t.sh/oauth/authorize` | |
| 70 | | Token | `https://api.g1t.sh/oauth/token` | |
| 71 | | Registration | `https://api.g1t.sh/oauth/register` | |
| 72 | |
| 73 | - The flow is authorization code with PKCE. `S256` is required. |
| 74 | - Clients are public: there are no client secrets. |
| 75 | - Register with `client_name` and `redirect_uris`. A redirect address is an |
| 76 | `https` URL, `http` on `localhost`, or the application's own scheme. A |
| 77 | client on `localhost` may use any port. |
| 78 | - Registration stores nothing. The client id it returns encodes what was |
| 79 | registered, so it cannot be used to fill g1t with junk. |
| 80 | - An access token lasts 30 days. The refresh token returned with it works |
| 81 | once and returns the next pair; the previous access token stops working. |
| 82 | - An authorization code lasts five minutes and works once. |
| 83 | |
| 84 | ## Signing in from a tool |
| 85 | |
| 86 | A tool that cannot receive a redirect, such as a script on a remote machine, |
| 87 | gets a token without ever handling your password, the same way |
| 88 | `gh auth login` works: |
| 89 | |
| 90 | 1. The tool asks g1t for a code and shows you a link and a short code such |
| 91 | as `WDJB-MJHT`. |
| 92 | 2. You open the link, sign in (or create an account), check that the code |
| 93 | matches, and approve. |
| 94 | 3. The tool collects its token. |
| 95 | |
| 96 | ```sh |
| 97 | # 1. The tool starts a sign-in. |
| 98 | curl -X POST https://api.g1t.sh/device/code -H "Content-Type: application/json" -d '{"client_name": "my-tool"}' |
| 99 | |
| 100 | # 2. You open verification_uri_complete from the response and approve. |
| 101 | |
| 102 | # 3. The tool polls, no faster than "interval" seconds, until it is approved. |
| 103 | curl -X POST https://api.g1t.sh/device/token -H "Content-Type: application/json" -d '{"device_code": "…"}' |
| 104 | ``` |
| 105 | |
| 106 | The poll answers with a `status` of `pending`, `approved`, `denied` or |
| 107 | `expired`. An approved answer carries the token, once. Codes expire after 15 |
| 108 | minutes. The token appears in your settings under the tool's name, where you |
| 109 | can delete it. |
| 110 | |
| 111 | Only approve a code you asked for. Approving gives the tool the full rights |
| 112 | of your account. |
| 113 | |
| 114 | ## Resetting your password |
| 115 | |
| 116 | Use [g1t.sh/forgot](https://g1t.sh/forgot). The emailed link works for one |
| 117 | hour. Setting a new password signs you out everywhere. |
| 118 | |
| 119 | ## What g1t stores |
| 120 | |
| 121 | Passwords are stored as salted PBKDF2-SHA256 hashes. Sessions and tokens are |
| 122 | stored as SHA-256 hashes. Neither can be read back. |