| 1 | --- |
| 2 | title: Accounts and authentication |
| 3 | description: Accounts, email confirmation, access tokens 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 | A workspace owns repositories and is the first part of their address: |
| 27 | `g1t.sh/<workspace>/<repo>`. There is one kind. A workspace for just you and |
| 28 | one for a company are the same thing with a different number of members, so |
| 29 | there is no separate notion of an organization. |
| 30 | |
| 31 | Your account does not own repositories itself. After confirming your email |
| 32 | you create a workspace, which can have the same name as your username, and |
| 33 | repositories go in it. You can belong to up to ten. |
| 34 | |
| 35 | | Role | Can | |
| 36 | | --- | --- | |
| 37 | | Member | Create repositories, push, manage issues, merge pull requests. | |
| 38 | | Owner | Everything a member can, and add or remove members. | |
| 39 | |
| 40 | Manage members on the workspace's page, `g1t.sh/<workspace>`. |
| 41 | |
| 42 | ## Access tokens |
| 43 | |
| 44 | A token stands in for your password everywhere outside the website: |
| 45 | |
| 46 | | Where | How to send it | |
| 47 | | --- | --- | |
| 48 | | git | As the password, with your username. | |
| 49 | | API | `Authorization: Bearer g1t_…` | |
| 50 | | MCP | The same header, set when you add the server. | |
| 51 | |
| 52 | Create one in [Settings](https://g1t.sh/settings). A token is shown once, |
| 53 | when it is created; g1t stores only a hash of it. If you lose one, delete it |
| 54 | and create another. Delete a token the moment you think someone else has |
| 55 | seen it. |
| 56 | |
| 57 | A token has the full rights of your account. Scoped tokens are planned. |
| 58 | |
| 59 | ## Signing in with OAuth |
| 60 | |
| 61 | Applications that can open your browser, such as an agent connecting to the |
| 62 | [MCP server](/guides/bring-your-own-agent/), sign you in with OAuth 2.1. |
| 63 | You see a page on g1t naming the application and where it will send you |
| 64 | back, and you approve or deny. The application never sees your password and |
| 65 | there is no token to copy. |
| 66 | |
| 67 | Applications you have approved are listed under **Connected applications** |
| 68 | in [Settings](https://g1t.sh/settings). Signing one out ends its access at |
| 69 | once. |
| 70 | |
| 71 | For people building a client: |
| 72 | |
| 73 | | | | |
| 74 | | --- | --- | |
| 75 | | Metadata | `https://api.g1t.sh/.well-known/oauth-authorization-server` | |
| 76 | | Authorization | `https://g1t.sh/oauth/authorize` | |
| 77 | | Token | `https://api.g1t.sh/oauth/token` | |
| 78 | | Registration | `https://api.g1t.sh/oauth/register` | |
| 79 | |
| 80 | - The flow is authorization code with PKCE. `S256` is required. |
| 81 | - Clients are public: there are no client secrets. |
| 82 | - Register with `client_name` and `redirect_uris`. A redirect address is an |
| 83 | `https` URL, `http` on `localhost`, or the application's own scheme. A |
| 84 | client on `localhost` may use any port. |
| 85 | - Registration stores nothing. The client id it returns encodes what was |
| 86 | registered, so it cannot be used to fill g1t with junk. |
| 87 | - An access token lasts 30 days. The refresh token returned with it works |
| 88 | once and returns the next pair; the previous access token stops working. |
| 89 | - An authorization code lasts five minutes and works once. |
| 90 | |
| 91 | ## Signing in from a tool |
| 92 | |
| 93 | A tool that cannot receive a redirect, such as a script on a remote machine, |
| 94 | gets a token without ever handling your password, the same way |
| 95 | `gh auth login` works: |
| 96 | |
| 97 | 1. The tool asks g1t for a code and shows you a link and a short code such |
| 98 | as `WDJB-MJHT`. |
| 99 | 2. You open the link, sign in (or create an account), check that the code |
| 100 | matches, and approve. |
| 101 | 3. The tool collects its token. |
| 102 | |
| 103 | ```sh |
| 104 | # 1. The tool starts a sign-in. |
| 105 | curl -X POST https://api.g1t.sh/v1/device/code -H "Content-Type: application/json" -d '{"client_name": "my-tool"}' |
| 106 | |
| 107 | # 2. You open verification_uri_complete from the response and approve. |
| 108 | |
| 109 | # 3. The tool polls, no faster than "interval" seconds, until it is approved. |
| 110 | curl -X POST https://api.g1t.sh/v1/device/token -H "Content-Type: application/json" -d '{"device_code": "…"}' |
| 111 | ``` |
| 112 | |
| 113 | The poll answers with a `status` of `pending`, `approved`, `denied` or |
| 114 | `expired`. An approved answer carries the token, once. Codes expire after 15 |
| 115 | minutes. The token appears in your settings under the tool's name, where you |
| 116 | can delete it. |
| 117 | |
| 118 | Only approve a code you asked for. Approving gives the tool the full rights |
| 119 | of your account. |
| 120 | |
| 121 | ## Resetting your password |
| 122 | |
| 123 | Use [g1t.sh/forgot](https://g1t.sh/forgot). The emailed link works for one |
| 124 | hour. Setting a new password signs you out everywhere. |
| 125 | |
| 126 | ## What g1t stores |
| 127 | |
| 128 | Passwords are stored as salted PBKDF2-SHA256 hashes. Sessions and tokens are |
| 129 | stored as SHA-256 hashes. Neither can be read back. |