| 1 | --- |
| 2 | title: Accounts and authentication |
| 3 | description: Accounts, invites, email addresses, confirming them, two-factor authentication and recovery codes, fine-grained and classic personal access tokens, scopes and permissions, a workspace's rules for tokens, OAuth, signing in from a tool, password reset, your security log and deleting your account. |
| 4 | --- |
| 5 | |
| 6 | ## Creating an account |
| 7 | |
| 8 | g1t is invite-only for now: to make an account you need an |
| 9 | [invite](#invites). Open the link in your invite, or enter its code at |
| 10 | [g1t.sh/register](https://g1t.sh/register). Without one, ask for access |
| 11 | on the same page. Usernames are lowercase letters, digits and single |
| 12 | hyphens, up to 39 characters. |
| 13 | |
| 14 | Before you can do anything else, you [confirm your email |
| 15 | address](#confirming-your-email-address) with the code g1t emails you. |
| 16 | |
| 17 | Accounts can only be created in a browser. There is no API for it, by |
| 18 | design: it keeps passwords out of scripts and agents, and lets g1t protect |
| 19 | the one place accounts are made. |
| 20 | |
| 21 | ## Your settings |
| 22 | |
| 23 | Your own settings are at [g1t.sh/settings](https://g1t.sh/settings), one |
| 24 | page each. Open them from your account menu at the bottom of the sidebar, |
| 25 | under **Your settings**; the sidebar then lists every page. |
| 26 | |
| 27 | | Page | Address | What is on it | |
| 28 | | --- | --- | --- | |
| 29 | | Profile | [`/settings/profile`](https://g1t.sh/settings/profile) | Your picture, and your [public profile](/guides/workspaces/#profiles): name, pronouns, bio, location, website and time zone. | |
| 30 | | Emails | [`/settings/emails`](https://g1t.sh/settings/emails) | Your [email addresses](#email-addresses), the backup address, and [keeping your address private](#keeping-your-address-private). | |
| 31 | | Invites | [`/settings/invites`](https://g1t.sh/settings/invites) | [Making, copying and revoking invites](#invites). | |
| 32 | | SSH keys | [`/settings/keys`](https://g1t.sh/settings/keys) | Public keys for [git over SSH](/guides/git/#ssh), each with when it was added and last used. | |
| 33 | | Access tokens | [`/settings/tokens`](https://g1t.sh/settings/tokens) | Your [personal access tokens](#access-tokens): fine-grained and classic. | |
| 34 | | GitHub | [`/settings/github`](https://g1t.sh/settings/github) | [Linking and unlinking GitHub](/guides/github/#link-and-unlink-github). | |
| 35 | | Connected applications | [`/settings/applications`](https://g1t.sh/settings/applications) | Tools you [signed in to with OAuth](#signing-in-with-oauth), such as an agent using the MCP server. | |
| 36 | | Two-factor authentication | [`/settings/two-factor`](https://g1t.sh/settings/two-factor) | [An authenticator app and recovery codes](#two-factor-authentication). | |
| 37 | | Security log | [`/settings/security-log`](https://g1t.sh/settings/security-log) | [What happened to your account](#security-log). | |
| 38 | | Account | [`/settings/account`](https://g1t.sh/settings/account) | Your username, and [deleting your account](#deleting-your-account). | |
| 39 | |
| 40 | `g1t.sh/settings` opens Profile. |
| 41 | |
| 42 | ## Signing in with GitHub |
| 43 | |
| 44 | **Continue with GitHub** on the sign-in and sign-up pages signs you in with |
| 45 | your GitHub account, and makes a g1t account the first time. Link or |
| 46 | unlink GitHub in [Settings → GitHub](https://g1t.sh/settings/github). See |
| 47 | [GitHub](/guides/github/#sign-in-with-github). |
| 48 | |
| 49 | Making an account with GitHub needs an invite too: start from your invite |
| 50 | link, or enter the code when g1t asks for it after GitHub. |
| 51 | |
| 52 | With [two-factor authentication](#two-factor-authentication) on, signing in |
| 53 | with GitHub asks for a code from your app as well. |
| 54 | |
| 55 | ## Two-factor authentication |
| 56 | |
| 57 | Two-factor authentication asks for a code from an authenticator app on |
| 58 | your phone each time you sign in with your password or with GitHub, so a |
| 59 | stolen password is not enough. Any app that reads a time-based one-time |
| 60 | password (TOTP) QR code works, such as 1Password, Google Authenticator or |
| 61 | Authy. |
| 62 | |
| 63 | ### Turn it on |
| 64 | |
| 65 | 1. Open [Settings → Two-factor authentication](https://g1t.sh/settings/two-factor) |
| 66 | and choose **Set up**. g1t asks for your password if you have not |
| 67 | signed in in the last 10 minutes. |
| 68 | 2. Scan the QR code with your app, or type the key shown under it. |
| 69 | 3. Enter the six-digit code the app shows, and choose **Turn on**. |
| 70 | 4. Save the ten recovery codes g1t shows. They are shown only then. |
| 71 | |
| 72 | ### Signing in with it on |
| 73 | |
| 74 | After your password (or GitHub), g1t asks for the code from your app. A |
| 75 | code works for 30 seconds, and the one before and after it are accepted |
| 76 | too, for a phone clock a little off. Each code works once. After five wrong |
| 77 | codes, or ten minutes, start the sign-in again. |
| 78 | |
| 79 | Lost your phone? Enter a recovery code instead of the app's code. Each |
| 80 | works once, and your security log records its use. |
| 81 | |
| 82 | Git over HTTPS never takes your password while two-factor authentication |
| 83 | is on: use a [personal access token](#access-tokens) as the password, or |
| 84 | [SSH](/guides/git/). Access tokens, SSH keys and OAuth applications are |
| 85 | not affected. |
| 86 | |
| 87 | ### Recovery codes, and turning it off |
| 88 | |
| 89 | On the same page: |
| 90 | |
| 91 | - **Make new recovery codes** replaces all ten; the old ones stop working. |
| 92 | - **Turn off** needs a code from your app or a recovery code, and your |
| 93 | password if you have not signed in in the last 10 minutes. |
| 94 | |
| 95 | You cannot turn it off while you own a workspace that |
| 96 | [requires it](/guides/workspaces/#require-two-factor-authentication): stop |
| 97 | requiring it there first, or hand the workspace to another owner. In a |
| 98 | workspace that requires it, turning it off holds you out of that workspace |
| 99 | until you turn it on again. |
| 100 | |
| 101 | Turning it on or off, and making new recovery codes, are emailed to your |
| 102 | primary and backup addresses, written to your [security log](#security-log), |
| 103 | and recorded in the [audit log](/guides/audit-log/) of each of your |
| 104 | workspaces as `two_factor.enabled` and `two_factor.disabled`. |
| 105 | |
| 106 | ### Require two-factor authentication |
| 107 | |
| 108 | An owner can require it of everyone with access to a workspace. See |
| 109 | [Workspaces](/guides/workspaces/#require-two-factor-authentication). |
| 110 | |
| 111 | Passkeys are not supported yet; they are next. |
| 112 | |
| 113 | ## Invites |
| 114 | |
| 115 | While g1t is invite-only, every new account needs an invite code, such as |
| 116 | `g1t-k7m2-q9xd-…`. People already on g1t make them, and g1t sends them to |
| 117 | people who [asked for access](#asking-for-access). An invite: |
| 118 | |
| 119 | - works once, for one new account; |
| 120 | - works for 30 days; |
| 121 | - when it was made for an email address, works only with that address; |
| 122 | - can be revoked by whoever made it until it is used, and after that until |
| 123 | the new account [confirms its email address](#confirming-your-email-address). |
| 124 | |
| 125 | ### Using an invite |
| 126 | |
| 127 | Every invite email links to `g1t.sh/invite/<code>`. That one page shows |
| 128 | who sent it and what it is for (joining a workspace, collaborating on a |
| 129 | repository, or just making an account), and finishes the job there: |
| 130 | |
| 131 | 1. **No account yet**: sign up on the page. When the invite was sent to |
| 132 | your address, the email field is filled in and locked. Choose a |
| 133 | username (one is suggested from your address) and a password, then |
| 134 | [confirm the address](#confirming-your-email-address) with the code g1t |
| 135 | emails it, even though the invite came there: an invite link can be |
| 136 | forwarded, so it does not prove the inbox is yours. Or select |
| 137 | **Continue with GitHub**: the invite rides along, and the account uses |
| 138 | the invited address when GitHub has verified it too, in which case no |
| 139 | confirmation is needed. |
| 140 | 2. **The address already has an account**: select **Sign in to accept**. |
| 141 | After you sign in, the invite is accepted for you. |
| 142 | 3. **Signed in as someone else**: an invite sent to one address works only |
| 143 | for an account that has confirmed that address. The page says so and |
| 144 | offers **Sign out and continue**. |
| 145 | |
| 146 | Once you have signed in, or your new account has confirmed its address, |
| 147 | you land in the workspace (or the repository) the invite was for, already |
| 148 | a member, with a one-time "You're in" banner, and it becomes the workspace |
| 149 | your sidebar shows. |
| 150 | |
| 151 | Signing up spends the invite at once, so nobody else can use it while you |
| 152 | confirm your address, but you join its workspace only when you confirm, in |
| 153 | the same step. Until then the invite shows as **confirming their email** to |
| 154 | whoever made it, and they can still revoke it. If the invite is revoked or |
| 155 | expires, or its workspace is deleted, before you confirm, your address is |
| 156 | confirmed all the same and g1t tells you the invite no longer applies: ask |
| 157 | whoever invited you to add you again. A |
| 158 | code typed at [g1t.sh/register](https://g1t.sh/register) goes to the |
| 159 | same page. |
| 160 | |
| 161 | An expired, revoked or used invite says which, and who sent it, so you |
| 162 | can ask them for a new one; or ask for access from the same page. |
| 163 | |
| 164 | ### Invite links for a group |
| 165 | |
| 166 | g1t sometimes hands one link to a group: an event's judges, readers of a |
| 167 | post, a community. It looks like |
| 168 | `https://g1t.sh/register?invite=g1t-k7m2-…` and opens sign-up with the |
| 169 | code filled in and the group named above the form, such as **Invited as |
| 170 | part of Launch week judges**. |
| 171 | |
| 172 | - **It makes your own account.** Each person who uses it gets a new |
| 173 | account, and then makes their own workspace. It does not add you to |
| 174 | anyone else's workspace; once you are in, a workspace's owners can add |
| 175 | you from its People page. |
| 176 | - **It may be for some email domains only.** When it is, the email field |
| 177 | says which, such as `example.com`, and sign-up takes only an address |
| 178 | there. Use your address at that organization; you confirm it like any |
| 179 | other. |
| 180 | - **It works a set number of times, until a set day.** Once every place |
| 181 | is taken, or the day has passed, or g1t has stopped it, the link gets |
| 182 | the same answer as any invite that cannot be used. Ask whoever shared |
| 183 | it, or [ask for access](#asking-for-access). |
| 184 | |
| 185 | Using the link spends one place in the same step that makes your account, |
| 186 | so two people signing up at the same moment can never take more places |
| 187 | than it has. Anyone with an account can still [make invites](#making-invites) |
| 188 | of their own; group links are made by g1t staff only. |
| 189 | |
| 190 | ### Making invites |
| 191 | |
| 192 | 1. Open [Settings → Invites](https://g1t.sh/settings/invites). |
| 193 | 2. Optionally enter the email address of the person you are inviting. |
| 194 | With one, g1t emails them the invite, and only that address can use it. |
| 195 | Without one, anyone with the link can, once. |
| 196 | 3. Select **Create invite**, then copy the link. |
| 197 | |
| 198 | Each person can have **5** invites out at a time. Pending and used invites |
| 199 | count; an invite you revoke, or one that expires before anyone uses it, |
| 200 | comes back to you. The list under the form shows each invite's state: |
| 201 | pending, confirming their email (used to sign up by someone who has not |
| 202 | confirmed their address yet), joined (with the username of who joined), |
| 203 | expired or revoked. You |
| 204 | must confirm your email before you can make invites. An agent's token and |
| 205 | a workspace's token cannot make them. |
| 206 | |
| 207 | ### Inviting someone into a workspace |
| 208 | |
| 209 | An owner can invite an email address straight into a workspace from its |
| 210 | People page; see [members and roles](/guides/workspaces/#members-and-roles). |
| 211 | When the address has no g1t account, the invite makes the account, which |
| 212 | joins the workspace once it confirms its email address, and it uses one |
| 213 | invite. Inviting someone who is |
| 214 | already on g1t costs nothing. |
| 215 | |
| 216 | ### Need more invites? |
| 217 | |
| 218 | Write to [hey@flagon.io](mailto:hey@flagon.io?subject=%5Bg1t%20Invites%5D%20) |
| 219 | with the subject `[g1t Invites]` and say who you would like to bring. g1t |
| 220 | can give more invites to you, or to a workspace, whose owners then share |
| 221 | them. Invites given to a workspace appear under |
| 222 | [Settings → Invites](https://g1t.sh/settings/invites) for |
| 223 | each of its owners, as a choice of whose invites to use. |
| 224 | |
| 225 | ### Asking for access |
| 226 | |
| 227 | Without an invite, [g1t.sh/register](https://g1t.sh/register) asks for your |
| 228 | email address and, if you like, what you will build. g1t emails that |
| 229 | address once to confirm you are on the list, and staff see the request |
| 230 | straight away. When they approve it, the invite comes to the same address, |
| 231 | sometimes with a note, and its link opens sign-up with the address filled |
| 232 | in. There is no fixed date: g1t opens up a few people at a time. Asking |
| 233 | again with the same address updates your request without another email; it |
| 234 | does not move you down the list. |
| 235 | |
| 236 | ### Invites through the API |
| 237 | |
| 238 | | Route | MCP tool and action | What it does | |
| 239 | | --- | --- | --- | |
| 240 | | [`GET /user/invites`](/reference/api/invites/list-invites/) | `account` `list_invites` | Your invites and how many you have left | |
| 241 | | [`POST /user/invites`](/reference/api/invites/create-invite/) | `account` `create_invite` | Make an invite, optionally for one `email` | |
| 242 | | [`DELETE /user/invites/{id}`](/reference/api/invites/revoke-invite/) | `account` `revoke_invite` | Revoke a pending invite, or one whose new account has not confirmed its address | |
| 243 | | [`POST /workspaces/{workspace}/invitations`](/reference/api/invites/invite-member/) | `workspace` `invite_member` | Invite an address into a workspace. Owners only. | |
| 244 | |
| 245 | ## Confirming your email address |
| 246 | |
| 247 | A new account confirms its email address before it can do anything else on |
| 248 | g1t. Right after you sign up, g1t emails the address from `noreply@g1t.sh` |
| 249 | with two ways to confirm it, either one enough: |
| 250 | |
| 251 | - a **six-digit code**, shown large in the email (and in its subject, so a |
| 252 | phone's notification shows it). Type it on the **Confirm your email** |
| 253 | page g1t takes you to. On a phone, the keyboard offers it from the |
| 254 | message. |
| 255 | - a **link**, for when you would rather click than type. It works whether |
| 256 | or not you are signed in, in any browser. |
| 257 | |
| 258 | The code and the link work for **60 minutes**, once. Using either ends the |
| 259 | other. **Send a new code** on the confirmation page sends a fresh code and |
| 260 | link, at most once a minute and 10 times an hour, and the ones before stop |
| 261 | working. |
| 262 | |
| 263 | | On the confirmation page | What it does | |
| 264 | | --- | --- | |
| 265 | | **Confirm email** | Checks the code. A wrong, used or expired code gets the same answer. After 10 wrong codes in an hour, codes for the account are not checked for a while (a minute, then longer); the link in the email still works. Wrong codes from one network are limited the same way. | |
| 266 | | **Send a new code** | A new code and link; the ones before stop working. | |
| 267 | | **Wrong address? Change it** | Replaces the address you signed up with and sends the new one a code. Only while the account has no confirmed address. | |
| 268 | | **Sign out** | Signs out. Sign in again to come back to the page. | |
| 269 | |
| 270 | ### Until you confirm |
| 271 | |
| 272 | An account that has not confirmed its address can only confirm it: |
| 273 | |
| 274 | - **The site** sends every page to the confirmation page, and back to where |
| 275 | you were going once you confirm. Signing in and out, password resets, |
| 276 | the confirmation link, and g1t's [policies](https://g1t.sh/policies), |
| 277 | security, support, status and pricing pages stay open. |
| 278 | - **The API** answers `403` with a message saying to confirm your address, |
| 279 | except for [`GET /user`](/reference/api/accounts/whoami/), |
| 280 | [`GET /user/emails`](/reference/api/accounts/list-emails/) and |
| 281 | [`POST /user/emails/confirm`](/reference/api/accounts/confirm-email/). |
| 282 | - **The MCP server** answers `403` with the same message. |
| 283 | - **Git** over HTTPS refuses pushes and fetches with your credentials, with |
| 284 | the same message. Package registries treat them as wrong credentials. |
| 285 | - You cannot create a workspace, join the one your invite named, make |
| 286 | invites or tokens, or approve a tool's sign-in. |
| 287 | |
| 288 | You cannot make a token before you confirm, so the API and MCP refusals |
| 289 | matter only for an account that made one before this rule existed. |
| 290 | |
| 291 | ### Addresses GitHub has confirmed |
| 292 | |
| 293 | An account made with **Continue with GitHub** starts confirmed: its address |
| 294 | is one GitHub has verified, so GitHub has already proved the inbox is |
| 295 | yours, and no code is sent. |
| 296 | |
| 297 | ### Accounts that never confirmed |
| 298 | |
| 299 | Accounts are confirmed once and stay confirmed. An account made before this |
| 300 | rule that never confirmed its address, or whose address another account |
| 301 | confirmed first, is held at the confirmation page the same way the next |
| 302 | time it signs in; **Send a new code** gets it a code, and **Change it** |
| 303 | gives it a new address. |
| 304 | |
| 305 | ### Confirming through the API |
| 306 | |
| 307 | | Route | MCP tool and action | What it does | |
| 308 | | --- | --- | --- | |
| 309 | | [`POST /user/emails/confirm`](/reference/api/accounts/confirm-email/) | `account` `confirm_email` | Confirm an address with the `code` from its email | |
| 310 | |
| 311 | The answer says whether the account is now confirmed (`verified`), the |
| 312 | workspace confirming joined it to (`joined`), or why its invite no longer |
| 313 | applies (`invite_lapsed`). |
| 314 | |
| 315 | ## Email addresses |
| 316 | |
| 317 | An account can have up to 10 email addresses. Manage them in |
| 318 | [Settings → Emails](https://g1t.sh/settings/emails). |
| 319 | |
| 320 | | An address that is | Can | |
| 321 | | --- | --- | |
| 322 | | Primary | Get account mail and password reset links. Exactly one, always confirmed once any address is. | |
| 323 | | Confirmed | Sign you in (type it instead of your username), ask for a password reset, and mark commits that carry it as yours. | |
| 324 | | Backup | Get security notices as well as the primary. Optional, and a confirmed address other than the primary. | |
| 325 | | Unconfirmed | Nothing yet. It is not yours until you enter the code or follow the link g1t sent it. | |
| 326 | |
| 327 | A confirmed address belongs to one account. Anyone can add an address they |
| 328 | have not confirmed; the first account to confirm it keeps it, and the |
| 329 | address leaves every other account that added it. An address another |
| 330 | account has confirmed cannot be added. |
| 331 | |
| 332 | ### Add an address |
| 333 | |
| 334 | 1. Open [Settings → Emails](https://g1t.sh/settings/emails). |
| 335 | 2. Enter the address under **Add an email address** and select **Add**. |
| 336 | 3. Enter the code g1t emails it, or follow the link in the same email. |
| 337 | Both work for 60 minutes; **Resend link** sends a new code and link, at |
| 338 | most once a minute and 10 times an hour, and ends the ones before. |
| 339 | |
| 340 | If your account had no confirmed address yet, the first one you confirm |
| 341 | becomes your primary. |
| 342 | |
| 343 | ### Choose your primary and backup |
| 344 | |
| 345 | Select **Make primary** beside a confirmed address. Under **Backup |
| 346 | address**, choose a confirmed address to get security notices too, or |
| 347 | **Primary address only**. |
| 348 | |
| 349 | ### Remove an address |
| 350 | |
| 351 | Select **Remove** beside it. You cannot remove your primary address (make |
| 352 | another one primary first) or your last confirmed address. |
| 353 | |
| 354 | ### Confirming it is you |
| 355 | |
| 356 | Adding or removing an address, changing your primary or backup, and |
| 357 | turning two-factor authentication on or off, need proof that it is you: a |
| 358 | sign-in in the last 10 minutes, or your password, |
| 359 | which g1t asks for on the page. After you enter it, g1t does not ask again |
| 360 | for 10 minutes. An account that signs in only with GitHub signs out and in |
| 361 | with GitHub again, or sets a password with |
| 362 | [Forgot your password](https://g1t.sh/forgot). |
| 363 | |
| 364 | Each of these changes is emailed to every confirmed address on the account, |
| 365 | including an address that was just removed, and written to your |
| 366 | [security log](#security-log). |
| 367 | |
| 368 | ### Keeping your address private |
| 369 | |
| 370 | **Keep my email address private** is on for every account unless you turn |
| 371 | it off. While it is on, commits g1t makes for you (merging a pull request |
| 372 | on the web, catching a branch up, and commits an agent makes for you) carry |
| 373 | your noreply address instead of your primary: |
| 374 | |
| 375 | ``` |
| 376 | <8 characters of your account id>+<username>@users.noreply.g1t.sh |
| 377 | ``` |
| 378 | |
| 379 | The page shows yours. It never receives mail. Turn the setting off to put |
| 380 | your primary address on those commits instead. |
| 381 | |
| 382 | **Block pushes that expose my email** refuses a push that would publish one |
| 383 | of your addresses while you keep it private. When both settings are on, |
| 384 | g1t reads the new commits in each push you make, and declines the push if |
| 385 | any of them has one of your confirmed addresses as its author or committer |
| 386 | address. git shows why, with the address masked: |
| 387 | |
| 388 | ``` |
| 389 | remote: push declined: commit 3f9a1c2 would publish s***@gmail.com while your email is private. |
| 390 | remote: Commit with 6c1d0efg+sam@users.noreply.g1t.sh (git config user.email 6c1d0efg+sam@users.noreply.g1t.sh) and amend, |
| 391 | remote: or change this in g1t.sh/settings/emails. |
| 392 | ``` |
| 393 | |
| 394 | To push those commits: |
| 395 | |
| 396 | 1. Set your noreply address for the repository: |
| 397 | `git config user.email <your noreply address>`. |
| 398 | 2. Rewrite the commits with it. For the last commit, |
| 399 | `git commit --amend --reset-author --no-edit`; for several, |
| 400 | `git rebase <base> --exec "git commit --amend --reset-author --no-edit"`. |
| 401 | 3. Push again. |
| 402 | |
| 403 | Only your own addresses are checked: commits by other people in the same |
| 404 | push go through, and so does your noreply address. A push an agent makes |
| 405 | for you follows your settings. |
| 406 | |
| 407 | ### How commits are attributed |
| 408 | |
| 409 | g1t shows a commit as yours, with your picture and a link to your profile, |
| 410 | when its author address is one of your confirmed addresses or your noreply |
| 411 | address. Commits that g1t made for you before noreply addresses existed |
| 412 | (`<username>@users.g1t.sh`) count as yours too. An unconfirmed address |
| 413 | never attributes a commit, so nobody can claim your commits by adding your |
| 414 | address. Commits whose address matches no account show the name in the |
| 415 | commit. See [Commits and your account](/guides/workspaces/#commits-and-your-account) |
| 416 | for setting your noreply address in git. |
| 417 | |
| 418 | ### Email addresses through the API |
| 419 | |
| 420 | | Route | MCP tool and action | What it does | |
| 421 | | --- | --- | --- | |
| 422 | | [`GET /user/emails`](/reference/api/accounts/list-emails/) | `account` `list_emails` | Your addresses and email settings | |
| 423 | | [`POST /user/emails`](/reference/api/accounts/add-email/) | `account` `add_email` | Add an address; takes `email` and `password` | |
| 424 | | [`POST /user/emails/confirm`](/reference/api/accounts/confirm-email/) | `account` `confirm_email` | Confirm an address with the `code` from its email | |
| 425 | | [`DELETE /user/emails/{email}`](/reference/api/accounts/remove-email/) | `account` `remove_email` | Remove an address; takes `password` | |
| 426 | | [`PATCH /user/email-settings`](/reference/api/accounts/update-email-settings/) | `account` `update_email_settings` | Change `primary`, `backup`, `private_email` or `block_private_pushes` | |
| 427 | |
| 428 | Through the API, `password` is the proof a sensitive change needs. Without |
| 429 | it, or with the wrong one, the answer is `403` with the code |
| 430 | `reauth_required`. Only a person's own token can use these: an agent's |
| 431 | token and a workspace's token are refused. |
| 432 | |
| 433 | ## Workspaces |
| 434 | |
| 435 | Your account does not own repositories itself: a workspace does. After |
| 436 | confirming your email, the first thing you do is create one. Workspaces, |
| 437 | their members and roles, and the access tokens that belong to a workspace |
| 438 | are covered in [workspaces](/guides/workspaces/). |
| 439 | |
| 440 | ## Access tokens |
| 441 | |
| 442 | A token stands in for your password everywhere outside the website: |
| 443 | |
| 444 | | Where | How to send it | |
| 445 | | --- | --- | |
| 446 | | git | As the password, with your username. | |
| 447 | | API | `Authorization: Bearer g1t_…` | |
| 448 | | MCP | The same header, set when you add the server. | |
| 449 | |
| 450 | A token is shown once, when it is created; g1t stores only a hash of it. |
| 451 | If you lose one, delete it and create another. Delete a token the moment |
| 452 | you think someone else has seen it. |
| 453 | |
| 454 | There are two kinds of personal access token, on two tabs of |
| 455 | [Settings → Access tokens](https://g1t.sh/settings/tokens): |
| 456 | |
| 457 | | | Fine-grained token | Classic token | |
| 458 | | --- | --- | --- | |
| 459 | | Reaches | One resource owner: one workspace you belong to, or your own account | Every workspace and repository you can reach, including ones you join later | |
| 460 | | Repositories | All of the workspace's, the ones you choose (up to 50), or public ones only | All you can reach | |
| 461 | | What it may do | A level for each [permission](#permissions) | Its [scopes](#scopes) | |
| 462 | | Expires | Always, within 366 days | 7 days to 1 year, or never | |
| 463 | | A workspace can | Require an owner's approval first, or keep them out | Keep them out | |
| 464 | |
| 465 | Both never do more than you could on the website, and both are sent the |
| 466 | same way. Prefer a fine-grained token: it reaches only what it needs. |
| 467 | |
| 468 | For CI and integrations that work for a team, a workspace can have tokens |
| 469 | of its own that act as the workspace and keep working when their creator |
| 470 | leaves. See [workspace tokens](#workspace-tokens). |
| 471 | |
| 472 | ### Create a fine-grained token |
| 473 | |
| 474 | 1. Open [Settings → Access tokens](https://g1t.sh/settings/tokens). The |
| 475 | **Fine-grained tokens** tab is first. |
| 476 | 2. Under **New fine-grained token**, give it a **Token name** after what |
| 477 | will use it, and optionally a **Description**, which a workspace's |
| 478 | owners see if they review it. |
| 479 | 3. Choose the **Resource owner**: a workspace you belong to, or **Your |
| 480 | account**. A workspace that does not allow fine-grained tokens cannot be |
| 481 | chosen. |
| 482 | 4. Choose its **Expiration**: 7, 30, 60, 90 or 180 days, or 1 year, or |
| 483 | less when the workspace sets a shorter limit. |
| 484 | 5. Under **Repository access**, choose **Public repositories** (read-only), |
| 485 | **All repositories** of the workspace (including ones made later), or |
| 486 | **Only select repositories**, and tick up to 50. |
| 487 | 6. Under **Permissions**, set each one the token needs to **Read-only** or |
| 488 | **Read and write** (and **Admin** for packages). **Metadata** is always |
| 489 | read-only. Each row shows the g1t scopes its level gives. |
| 490 | 7. Select **Generate token**, and copy it. It is not shown again. |
| 491 | |
| 492 | When the workspace [requires approval](#a-workspaces-rules-for-tokens) and |
| 493 | you are not one of its owners, the token is made **Pending approval**: it |
| 494 | works at once, but reads public repositories only until an owner approves |
| 495 | it. The owners hear of it in their [inbox](/guides/inbox/), and you hear of |
| 496 | their answer in yours. An owner's own token never waits. |
| 497 | |
| 498 | Select **Edit** on a token to change its name, description, repositories |
| 499 | or permissions. The token stays the same. Widening it in a workspace that |
| 500 | requires approval asks again. Its resource owner and expiry cannot change; |
| 501 | make a new token instead. |
| 502 | |
| 503 | The list shows each token's status (pending, denied or revoked, with the |
| 504 | owner's note), what it reaches, its permissions, and when it was made, last |
| 505 | used and expires. |
| 506 | |
| 507 | ### Permissions |
| 508 | |
| 509 | Each level of a fine-grained token's permissions gives g1t |
| 510 | [scopes](#scopes), and the token is checked by those scopes |
| 511 | exactly as a classic token is. Where two permissions give the same scopes |
| 512 | (Checks and Commit statuses; Secrets and Variables; Deployments and Pages), |
| 513 | giving either gives both. |
| 514 | |
| 515 | Repository permissions, for a workspace as the resource owner: |
| 516 | |
| 517 | | Permission | Levels | What it covers | g1t scopes it gives | |
| 518 | | --- | --- | --- | --- | |
| 519 | | `actions` (Actions) | read, write | Workflow runs, jobs, logs and artifacts: reading them, and running, cancelling and rerunning workflows | read: `workflows:read`; write: `workflows:write` | |
| 520 | | `administration` (Administration) | read, write | Repository settings, rulesets, who has access and deploy keys; renaming, archiving, transferring and deleting | read: `repo:read`, `access:read`; write: `repo:admin`, `access:admin` | |
| 521 | | `agents` (g1t agents) | write | Putting g1t's agents to work and messaging them, which uses the workspace's money | write: `agents:run` | |
| 522 | | `checks` (Checks) | read, write | Check runs and check suites on commits. Shares its scopes with Commit statuses | read: `checks:read`; write: `checks:write` | |
| 523 | | `contents` (Contents) | read, write | Code, branches, commits and releases: cloning and fetching, pushing, and publishing releases | read: `code:read`; write: `code:write`, `repo:write` | |
| 524 | | `deployments` (Deployments) | read, write | Deployments and their statuses | read: `deployments:read`; write: `deployments:write` | |
| 525 | | `environments` (Environments) | read, write | Environments, and their secrets and variables | read: `deployments:read`, `secrets:read`; write: `secrets:admin` | |
| 526 | | `issues` (Issues) | read, write | Issues, their comments, labels and milestones, and plans | read: `issues:read`; write: `issues:write` | |
| 527 | | `memory` (Memory and context) | read, write | Recalling memory and searching the workspace's context, and saving memory for the next agent | read: `memory:read`; write: `memory:write` | |
| 528 | | `metadata` (Metadata) | read | Seeing repositories and searching them. Always read | read: `repo:read` | |
| 529 | | `packages` (Packages) | read, write, admin | Pulling private packages, publishing them, and (admin) deleting packages and versions | read: `packages:read`; write: `packages:write`; admin: `packages:delete` | |
| 530 | | `pages` (Pages) | read, write | Deployments on g1t.page. Shares its scopes with Deployments | read: `deployments:read`; write: `deployments:write` | |
| 531 | | `pull_requests` (Pull requests) | read, write | Pull requests, their reviews, changes, sessions and merge queues | read: `pull_requests:read`; write: `pull_requests:write` | |
| 532 | | `secrets` (Secrets) | read, write | Actions secrets: listing them (never their values), setting and deleting them. Shares its scopes with Variables | read: `secrets:read`; write: `secrets:admin` | |
| 533 | | `security_events` (Security events and alerts) | read, write | Code scanning, secret scanning and vulnerability alerts, SARIF uploads and security settings | read: `security:read`; write: `security:write` | |
| 534 | | `statuses` (Commit statuses) | read, write | Statuses on commits. Shares its scopes with Checks | read: `checks:read`; write: `checks:write` | |
| 535 | | `variables` (Variables) | read, write | Actions variables: reading, setting and deleting them. Shares its scopes with Secrets | read: `secrets:read`; write: `secrets:admin` | |
| 536 | | `webhooks` (Webhooks) | read, write | Webhooks and their deliveries | read: `webhooks:read`; write: `webhooks:admin` | |
| 537 | | `workflows` (Workflows) | write | Adding, changing and deleting workflow files under .g1t/workflows and .github/workflows. Write only | write: `workflow_files:write` | |
| 538 | |
| 539 | Workspace permissions, for a workspace as the resource owner: |
| 540 | |
| 541 | | Permission | Levels | What it covers | g1t scopes it gives | |
| 542 | | --- | --- | --- | --- | |
| 543 | | `members` (Members) | read, write | The workspace's people, invitations and teams | read: `workspace:read`; write: `workspace:admin` | |
| 544 | | `workspace_administration` (Administration) | read, write | The workspace's settings, integrations, rulesets and base permission | read: `workspace:read`, `access:read`; write: `workspace:admin`, `access:admin` | |
| 545 | | `workspace_billing` (Billing) | read, write | Usage, budget, AI credit and invoices, and (write) changing the budget and buying credit | read: `billing:read`; write: `billing:write` | |
| 546 | | `models` (AI Gateway) | read, write | AI Gateway requests: seeing them, and sending requests, which uses the workspace's AI credit | read: `models:read`; write: `models:write` | |
| 547 | | `self_hosted_runners` (Self-hosted runners) | read, write | Runners, their groups and settings | read: `runners:read`; write: `runners:admin` | |
| 548 | | `workspace_secrets` (Secrets) | read, write | The workspace's Actions secrets. Shares its scopes with the repository Secrets permission | read: `secrets:read`; write: `secrets:admin` | |
| 549 | | `workspace_webhooks` (Webhooks) | read, write | The workspace's webhooks. Shares its scopes with the repository Webhooks permission | read: `webhooks:read`; write: `webhooks:admin` | |
| 550 | |
| 551 | Account permissions, for your own account as the resource owner: |
| 552 | |
| 553 | | Permission | Levels | What it covers | g1t scopes it gives | |
| 554 | | --- | --- | --- | --- | |
| 555 | | `email_addresses` (Email addresses) | read, write | Your email addresses and email settings, invites and invitations | read: `account:read`; write: `account:write` | |
| 556 | | `starring` (Starring) | read, write | Stars and pinned projects. Shares its scopes with Email addresses | read: `account:read`; write: `account:write` | |
| 557 | | `notifications` (Notifications) | read, write | Your inbox, subscriptions and watched repositories | read: `notifications:read`; write: `notifications:write` | |
| 558 | |
| 559 | ### What a fine-grained token reaches |
| 560 | |
| 561 | - **In its workspace**, what your role allows, in the repositories it |
| 562 | reaches, and only what its permissions give. |
| 563 | - **Elsewhere**, public repositories, read-only, as anyone can. It cannot |
| 564 | comment, open issues or push there. |
| 565 | - **With your account as its resource owner**, public repositories, |
| 566 | read-only, and what its account permissions give. |
| 567 | - **While pending, denied or revoked**, public repositories, read-only. |
| 568 | |
| 569 | A request it cannot make answers `403` naming why: the scope it lacks, or |
| 570 | `This fine-grained token's resource owner is the workspace acme: it can only |
| 571 | read public repositories elsewhere, …`. A repository outside its selection |
| 572 | answers as if it did not exist. |
| 573 | |
| 574 | ### Create a classic token |
| 575 | |
| 576 | 1. Open [Settings → Access tokens](https://g1t.sh/settings/tokens), and |
| 577 | select the **Tokens (classic)** tab. |
| 578 | 2. Under **New classic token**, give it a **Name** after what will use it. |
| 579 | 3. Choose when it **Expires**: 7 days, 30 days, 90 days (the default), |
| 580 | 1 year, or No expiry. An expired token stops working; make a new one. |
| 581 | No expiry shows a warning: the token works until someone deletes it. |
| 582 | 4. Under **Scopes**, tick the boxes for what it may do. They are grouped |
| 583 | by area. The form starts on the **Agent** [preset](#presets); select |
| 584 | another preset to tick its boxes instead. |
| 585 | 5. Select **Create token**, and copy the token. It is not shown again. |
| 586 | |
| 587 | The list shows each token's name, when it was made and last used, when it |
| 588 | expires, and its access: a preset's name, its scopes, or Full access. To |
| 589 | change what a token may do, select **Edit access**, tick or untick boxes, |
| 590 | and select **Save access**. The token stays the same; the change applies |
| 591 | from its next request. |
| 592 | |
| 593 | A classic token reaches every workspace you belong to unless the |
| 594 | workspace's [rules](#a-workspaces-rules-for-tokens) keep it out: one that |
| 595 | does not allow classic tokens, one whose longest lifetime this token |
| 596 | exceeds, or one whose owner revoked it there. It keeps working everywhere |
| 597 | else. |
| 598 | |
| 599 | ## Scopes |
| 600 | |
| 601 | A scope is a resource and a level, written `resource:level`, such as |
| 602 | `issues:write`. A higher level includes the lower ones of the same |
| 603 | resource: `repo:admin` includes `repo:write`, which includes `repo:read`. |
| 604 | It never includes another resource: `repo:admin` does not let a token push, |
| 605 | which is `code:write`. |
| 606 | |
| 607 | On the form, scopes are a checklist grouped by area: |
| 608 | |
| 609 | | Group | Scopes | |
| 610 | | --- | --- | |
| 611 | | Repositories & code | `repo:read`, `repo:write`, `code:read`, `code:write` | |
| 612 | | Packages | `packages:read`, `packages:write` | |
| 613 | | Issues & pull requests | `issues:read`, `issues:write`, `pull_requests:read`, `pull_requests:write` | |
| 614 | | Agents | `agents:run` | |
| 615 | | Workflows | `workflows:read`, `workflows:write`, `workflow_files:write` | |
| 616 | | Checks | `checks:read`, `checks:write` | |
| 617 | | Deployments | `deployments:read`, `deployments:write` | |
| 618 | | Memory & search | `memory:read`, `memory:write` | |
| 619 | | Account | `account:read`, `account:write` | |
| 620 | | Notifications | `notifications:read`, `notifications:write` | |
| 621 | | Security | `security:read`, `security:write` | |
| 622 | | Workspace | `workspace:read`, `access:read`, `webhooks:read`, `secrets:read` | |
| 623 | | Billing | `billing:read`, `billing:write` | |
| 624 | | Runners | `runners:read` | |
| 625 | | AI Gateway | `models:read`, `models:write` | |
| 626 | | Dangerous | `repo:admin`, `packages:delete`, `workspace:admin`, `access:admin`, `webhooks:admin`, `secrets:admin`, `runners:admin` | |
| 627 | |
| 628 | Ticking a higher level ticks the lower ones of its resource and greys |
| 629 | them out: tick `issues:write` and `issues:read` is ticked too. Untick |
| 630 | `issues:write` and `issues:read` stays ticked. |
| 631 | |
| 632 | | Scope | What it lets a token do | |
| 633 | | --- | --- | |
| 634 | | `repo:read` | See repositories, their settings, labels, timelines, releases, languages, contributors and security alerts, and search | |
| 635 | | `repo:write` | Create repositories, rename branches, change how pull requests merge and publish releases | |
| 636 | | `repo:admin` | Rename, archive, transfer, delete or change who can see a repository, and dismiss security alerts | |
| 637 | | `code:read` | Clone and fetch private repositories with git | |
| 638 | | `code:write` | Push commits with git | |
| 639 | | `security:read` | See [secret scanning](/guides/security/secret-protection/), [code scanning](/guides/security/code-scanning/) and vulnerability alerts, custom patterns, the dependency graph and SBOM, and security settings | |
| 640 | | `security:write` | Dismiss and reopen alerts, bypass push protection, review bypass requests, manage custom patterns, upload SARIF and change security settings | |
| 641 | | `packages:read` | Pull container images and install private [packages](/guides/packages/). Public ones need no scope. | |
| 642 | | `packages:write` | Push container images and publish packages; with the Admin role on a package, change its settings | |
| 643 | | `packages:delete` | Delete and restore packages and their versions | |
| 644 | | `issues:read` | Read issues, comments and plans | |
| 645 | | `issues:write` | Open, edit, close and comment on issues | |
| 646 | | `pull_requests:read` | Read pull requests, their changes, sessions and merge queues | |
| 647 | | `pull_requests:write` | Open, review, close and merge pull requests | |
| 648 | | `agents:run` | Put g1t to work and message it, which uses the workspace's money | |
| 649 | | `workflows:read` | Read workflows, runs and logs | |
| 650 | | `workflows:write` | Run, cancel, rerun and turn workflows on or off | |
| 651 | | `workflow_files:write` | Add, change and delete [workflow files](#workflow-files) under `.g1t/workflows` and `.github/workflows`, with git or the API. Not in any preset but full access. | |
| 652 | | `checks:read` | Read commits' statuses, check runs, check suites and annotations | |
| 653 | | `checks:write` | Report [statuses and check runs](/guides/checks/) on commits, and ask for checks to run again | |
| 654 | | `deployments:read` | See [deployments](/guides/deployments-api/), their statuses and environments | |
| 655 | | `deployments:write` | Report deployments and their statuses, from any CI | |
| 656 | | `memory:read` | Recall memory and search the workspace's context | |
| 657 | | `memory:write` | Save memory for the next agent | |
| 658 | | `account:read` | Read your email addresses, invites, invitations, pinned projects and stars | |
| 659 | | `account:write` | Change your email addresses, make invites, answer invitations, pin projects and star repositories | |
| 660 | | `notifications:read` | See your [inbox](/guides/inbox/), its threads, and what you subscribe to and watch | |
| 661 | | `notifications:write` | Mark notifications read, done, saved or snoozed, subscribe to threads and watch repositories | |
| 662 | | `workspace:read` | Read workspace settings, invites, integrations, model routes and [teams](/guides/teams/) | |
| 663 | | `workspace:admin` | Create and delete workspaces, invite members, manage teams, connect integrations | |
| 664 | | `billing:read` | See a workspace's [usage, budget, AI credit and invoices](/guides/usage-and-billing/) | |
| 665 | | `billing:write` | Change a workspace's budget and buy AI credit. Only owners, as people: a workspace's own token and g1t's agents never change billing, whatever their scopes. Not in any preset but full access. | |
| 666 | | `access:read` | See who has access to repositories | |
| 667 | | `access:admin` | Give people and teams access to repositories, and take it away | |
| 668 | | `webhooks:read` | See webhooks and their deliveries | |
| 669 | | `webhooks:admin` | Create, change and delete webhooks | |
| 670 | | `secrets:read` | List secrets (never their values) and read variables | |
| 671 | | `secrets:admin` | Set and delete secrets and variables | |
| 672 | | `runners:read` | See [self-hosted runners](/guides/self-hosted-runners/), their groups and where agents run. Not in the Agent preset. | |
| 673 | | `runners:admin` | Register and remove self-hosted runners, change their groups and settings | |
| 674 | | `models:read` | See the workspace's [AI Gateway](/guides/ai-gateway/) requests: their models, tokens, cost and status | |
| 675 | | `models:write` | Send model requests through the [AI Gateway](/guides/ai-gateway/), which uses the workspace's AI credit. Only a workspace's own token can send them. Not in any preset but full access. | |
| 676 | |
| 677 | Every operation of the API and the MCP server needs exactly one of these, |
| 678 | except `whoami` (`GET /user`), which any token may use. Each endpoint's page |
| 679 | in the [API reference](/reference/api/) names its scope, and so does each |
| 680 | action in [MCP tools](/reference/mcp/). A few calls need a second scope for |
| 681 | what they ask: |
| 682 | |
| 683 | | Call | Also needs | |
| 684 | | --- | --- | |
| 685 | | `delegate` (`POST /repos/{owner}/{name}/issues/delegate`, the `agent` tool's `delegate`), which opens an issue | `issues:write`, beside `agents:run` | |
| 686 | | `apply_plan` or `import_issue` (the `plan` tool's `apply`, the `issue` tool's `import`) with `assign: true` | `agents:run` | |
| 687 | | `update_repo` with `private` or `default_branch` | `repo:admin` | |
| 688 | |
| 689 | ### What a token can do |
| 690 | |
| 691 | What a request may do is where these overlap: |
| 692 | |
| 693 | 1. **Your role.** A token never does more than you could on the website. A |
| 694 | token with `repo:admin` still cannot delete a repository unless you are |
| 695 | an owner of its workspace. See [access and roles](/guides/access-and-roles/). |
| 696 | 2. **What it reaches.** A classic token, every workspace and repository you |
| 697 | can reach, including ones you join later, unless a workspace's |
| 698 | [rules](#a-workspaces-rules-for-tokens) keep it out. A fine-grained |
| 699 | token, its [resource owner](#what-a-fine-grained-token-reaches) only. |
| 700 | 3. **Its scopes.** What kinds of thing it may do: chosen directly on a |
| 701 | classic token, given by its permissions on a fine-grained one. |
| 702 | |
| 703 | To keep a token away from other workspaces, make a fine-grained one, or use |
| 704 | a [workspace token](#workspace-tokens): it reaches only its own workspace. |
| 705 | |
| 706 | ### Presets |
| 707 | |
| 708 | A preset ticks a starting set of boxes. Select one, then tick or untick |
| 709 | any box. |
| 710 | |
| 711 | | Preset | Scopes | |
| 712 | | --- | --- | |
| 713 | | Read only | Every `read` scope. Changes nothing. | |
| 714 | | Agent | Every `read` scope except `runners:read`, and `code:write`, `issues:write`, `pull_requests:write`, `agents:run`, `memory:write` and `notifications:write`. Reads everything, works on issues and pull requests, pushes code, puts g1t to work, and answers your inbox. No admin scope. | |
| 715 | | CI | `repo:read`, `code:read`, `code:write`, `packages:read`, `packages:write`, `workflows:read`, `workflows:write`, `checks:read`, `checks:write`, `deployments:read` and `deployments:write`. Clones and pushes code, pushes and pulls packages, runs workflows, and reports [checks](/guides/checks/) and deployments. | |
| 716 | | Full access | Everything you can do, including deleting repositories and changing who has access. Marked **Dangerous**. | |
| 717 | |
| 718 | Admin scopes change things that are hard to undo, or decide who can reach |
| 719 | what. They are under **Dangerous**, with a warning. Give them only to |
| 720 | something you trust as much as yourself. |
| 721 | |
| 722 | ### Git and scopes |
| 723 | |
| 724 | Over HTTPS, git checks the same token: |
| 725 | |
| 726 | | To | Needs | |
| 727 | | --- | --- | |
| 728 | | Clone or fetch a public repository | No scope | |
| 729 | | Clone or fetch a private repository | `code:read` | |
| 730 | | Push | `code:write` | |
| 731 | | Push commits that add, change or delete [workflow files](#workflow-files) | `code:write` and `workflow_files:write` | |
| 732 | |
| 733 | Your role on the repository applies too, as on the website. A refused push |
| 734 | or clone says which scope is missing. |
| 735 | |
| 736 | ### Workflow files |
| 737 | |
| 738 | A workflow runs with its repository's secrets and a token of its own, so |
| 739 | changing one is as powerful as holding those. A token therefore needs |
| 740 | `workflow_files:write` (a fine-grained token's **Workflows** permission) to |
| 741 | add, change or delete any file under `.g1t/workflows/` or |
| 742 | `.github/workflows/`, besides `code:write`: |
| 743 | |
| 744 | - **With git**, every commit a push adds is compared with its parent, and a |
| 745 | push that changes a workflow file is declined, naming it: |
| 746 | |
| 747 | ```text |
| 748 | remote: This access token cannot change the workflow file .github/workflows/ci.yml: it needs the workflow_files:write scope. |
| 749 | remote: Push with a token that has the workflow_files:write scope, or make the change signed in on g1t.sh. |
| 750 | ``` |
| 751 | |
| 752 | A push too large for g1t to read whole is declined for such a token too, |
| 753 | since it cannot be checked; push it in smaller parts. |
| 754 | - **Through g1t**, a file written for a token (such as a starter workflow) |
| 755 | is refused the same way. |
| 756 | - **A workflow job's token** never may, whatever its `permissions:` say. |
| 757 | See [the job's token](/guides/actions/#the-jobs-token). |
| 758 | - **Signed in on g1t.sh**, your role decides, as for any file. |
| 759 | |
| 760 | Full-access tokens, and tokens made before scopes, include it. A |
| 761 | [deploy key](/guides/git/#deploy-keys) with write access may change |
| 762 | workflow files. |
| 763 | |
| 764 | ### When a token lacks a scope |
| 765 | |
| 766 | The API answers `403` with the scope that was missing in `needed_scope`: |
| 767 | |
| 768 | ```json |
| 769 | { |
| 770 | "error": { |
| 771 | "code": "forbidden", |
| 772 | "message": "This access token needs the issues:write scope to use create_issue.", |
| 773 | "needed_scope": "issues:write" |
| 774 | } |
| 775 | } |
| 776 | ``` |
| 777 | |
| 778 | Through MCP the same message comes back as a tool result with `isError` |
| 779 | set. Give the token that scope with **Edit access**, or make a new token. |
| 780 | |
| 781 | ### Tokens made before scopes |
| 782 | |
| 783 | Tokens and OAuth sign-ins made before tokens had scopes keep full access, |
| 784 | so nothing that uses them stops working. Settings marks each one |
| 785 | **Legacy · full access**, and says to narrow it to what it needs. For a |
| 786 | token, select **Narrow this token**; for an application, **Change access** |
| 787 | in [Connected applications](https://g1t.sh/settings/applications). Then |
| 788 | tick its scopes. A token you make with Full access on purpose is not marked |
| 789 | legacy. |
| 790 | |
| 791 | A token from [signing in from a tool](#signing-in-from-a-tool), such as the |
| 792 | g1t CLI, has full access. |
| 793 | |
| 794 | ### Workspace tokens |
| 795 | |
| 796 | A workspace's own tokens act as the workspace rather than a person. An |
| 797 | owner makes them in the workspace's **Settings → Access tokens**, with the |
| 798 | same checklist and expiry choices; the form starts on the CI preset. A |
| 799 | workspace token reaches all of that workspace's repositories, never |
| 800 | another workspace, and cannot manage people, tokens or workspaces. |
| 801 | |
| 802 | It has the Write role on the workspace's repositories, as a member does: |
| 803 | it pushes, merges and works on issues and pull requests, within its scopes. |
| 804 | Tick **Admin on the workspace's repositories** when making it to give it |
| 805 | Admin instead, so it can also manage webhooks, secrets, deploy keys and who |
| 806 | has access, and manage teams as an owner would. Only an owner can, and only |
| 807 | when making it. See |
| 808 | [workspace access tokens](/guides/workspaces/#workspace-access-tokens). |
| 809 | |
| 810 | ## A workspace's rules for tokens |
| 811 | |
| 812 | An owner decides which of the members' own personal tokens reach the |
| 813 | workspace, under its **Settings → Personal access tokens** |
| 814 | (`g1t.sh/<workspace>/-/personal-access-tokens`). The rules apply from each |
| 815 | token's next request, to tokens made before them too. A token they keep out |
| 816 | keeps working everywhere else, and reads the workspace's public |
| 817 | repositories as anyone can. |
| 818 | |
| 819 | | Rule | Default | What it does | |
| 820 | | --- | --- | --- | |
| 821 | | Allow fine-grained personal access tokens | On | Off: no fine-grained token can name the workspace as its resource owner, and existing ones stop reaching it. | |
| 822 | | Require approval of fine-grained tokens | On | A member's fine-grained token naming the workspace waits for an owner's approval, and again when it is widened. Owners' own tokens never wait. | |
| 823 | | Allow classic personal access tokens | On | Off: classic tokens no longer reach the workspace. | |
| 824 | | Tokens must expire | Off | On: a token that never expires does not reach the workspace. | |
| 825 | | Longest lifetime | No limit | A token that lasts longer (from when it was made to when it expires), or never expires, does not reach the workspace. Fine-grained tokens for it cannot be made longer. | |
| 826 | |
| 827 | The same page lists: |
| 828 | |
| 829 | - **Waiting for approval.** Each pending fine-grained token with its owner, |
| 830 | permissions, repositories and expiry. Add an optional note, then select |
| 831 | **Approve** or **Deny**. Its owner hears of it in their inbox, with the |
| 832 | note. |
| 833 | - **Tokens that can reach the workspace.** Every fine-grained token naming |
| 834 | it, and every classic token of its members and outside collaborators that |
| 835 | has not expired, with its owner, permissions or scopes, last use and |
| 836 | expiry, and whether it reaches the workspace now (and if not, why). Never |
| 837 | the token itself. Select **Revoke** to take one out: a fine-grained token |
| 838 | stops reaching the workspace for good; a classic token keeps working |
| 839 | everywhere else, but never reaches this workspace again. |
| 840 | |
| 841 | Approvals, denials, revocations and rule changes are |
| 842 | [audit log](/guides/audit-log/) entries: `token.approval_requested`, |
| 843 | `token.approved`, `token.denied`, `token.revoked` and |
| 844 | `token.policy_changed`. |
| 845 | |
| 846 | ### A workspace's rules through the API |
| 847 | |
| 848 | Owners, as people (a personal token with the scope works; a workspace's own |
| 849 | token does not): |
| 850 | |
| 851 | | Route | MCP tool and action | What it does | Scope | |
| 852 | | --- | --- | --- | --- | |
| 853 | | [`GET /workspaces/{workspace}/personal-access-token-policy`](/reference/api/personal-access-tokens/get-token-policy/) | `workspace` `get_token_policy` | The rules. Members may read them. | `workspace:read` | |
| 854 | | [`PATCH /workspaces/{workspace}/personal-access-token-policy`](/reference/api/personal-access-tokens/set-token-policy/) | `workspace` `set_token_policy` | Change `allow_classic`, `allow_fine_grained`, `require_approval`, `max_lifetime_days` (0 for no limit) or `forbid_no_expiry` | `workspace:admin` | |
| 855 | | [`GET /workspaces/{workspace}/personal-access-tokens`](/reference/api/personal-access-tokens/list-member-tokens/) | `workspace` `list_member_tokens` | The tokens that can reach it; `kind` is `classic` or `fine_grained` | `access:read` | |
| 856 | | [`GET /workspaces/{workspace}/personal-access-token-requests`](/reference/api/personal-access-tokens/list-token-requests/) | `workspace` `list_token_requests` | The fine-grained tokens waiting for approval | `access:read` | |
| 857 | | [`POST /workspaces/{workspace}/personal-access-token-requests/{id}`](/reference/api/personal-access-tokens/review-token-request/) | `workspace` `review_token_request` | `decision` is `approve` or `deny`, with an optional `reason` | `access:admin` | |
| 858 | | [`POST /workspaces/{workspace}/personal-access-tokens/{id}`](/reference/api/personal-access-tokens/revoke-member-token/) | `workspace` `revoke_member_token` | Revoke a token in the workspace, with an optional `reason` | `access:admin` | |
| 859 | |
| 860 | ## Signing in with OAuth |
| 861 | |
| 862 | Applications that can open your browser, such as an agent connecting to the |
| 863 | [MCP server](/guides/bring-your-own-agent/), sign you in with OAuth 2.1. |
| 864 | You see a page on g1t naming the application and where it will send you |
| 865 | back, and you approve or deny. The application never sees your password and |
| 866 | there is no token to copy. |
| 867 | |
| 868 | The page lists what the application will be able to do, as the same |
| 869 | checklist a token has, with only the scopes it asked for, all ticked. |
| 870 | Untick anything you would rather it could not do, leaving at least one; |
| 871 | you cannot give it more than it asked for. Like a token, it reaches |
| 872 | everything you can. |
| 873 | |
| 874 | An application that asks for no scopes in particular gets the |
| 875 | [Agent preset](#presets): every `read` scope except `runners:read`, and `code:write`, |
| 876 | `issues:write`, `pull_requests:write`, `agents:run`, `memory:write` and |
| 877 | `notifications:write`. |
| 878 | It never gets an admin scope unless it asks for one and you leave it |
| 879 | ticked. |
| 880 | |
| 881 | Applications you have approved are listed in |
| 882 | [Settings → Connected applications](https://g1t.sh/settings/applications), |
| 883 | each with its access. Select **Change access** to tick or untick its |
| 884 | scopes, then **Save access**: it stays signed in, the change applies at |
| 885 | once, and its next refresh keeps it. Select **Sign out** to end its access |
| 886 | at once. |
| 887 | |
| 888 | For people building a client: |
| 889 | |
| 890 | | | | |
| 891 | | --- | --- | |
| 892 | | Metadata | `https://api.g1t.sh/.well-known/oauth-authorization-server` | |
| 893 | | Authorization | `https://g1t.sh/oauth/authorize` | |
| 894 | | Token | `https://api.g1t.sh/oauth/token` | |
| 895 | | Registration | `https://api.g1t.sh/oauth/register` | |
| 896 | |
| 897 | - The flow is authorization code with PKCE. `S256` is required. |
| 898 | - Clients are public: there are no client secrets. |
| 899 | - Register with `client_name` and `redirect_uris`. A redirect address is an |
| 900 | `https` URL, `http` on `localhost`, or the application's own scheme. A |
| 901 | client on `localhost` may use any port. |
| 902 | - Registration stores nothing. The client id it returns encodes what was |
| 903 | registered, so it cannot be used to fill g1t with junk. |
| 904 | - Ask for scopes with `scope` on the authorization request, separated by |
| 905 | spaces, such as `scope=repo:read issues:write pull_requests:write`. |
| 906 | Names g1t does not know are left out. Leave `scope` out for the Agent |
| 907 | preset. The authorization server's metadata and |
| 908 | `https://mcp.g1t.sh/.well-known/oauth-protected-resource` list every |
| 909 | scope in `scopes_supported`. |
| 910 | - The token response's `scope` holds the scopes the person granted, |
| 911 | separated by spaces, or `*` for a sign-in with full access. Refreshing |
| 912 | keeps them. |
| 913 | - An access token lasts 30 days. The refresh token returned with it works |
| 914 | once and returns the next pair; the previous access token stops working. |
| 915 | - An authorization code lasts five minutes and works once. |
| 916 | |
| 917 | ## Signing in from a tool |
| 918 | |
| 919 | A tool that cannot receive a redirect, such as a script on a remote machine, |
| 920 | gets a token without ever handling your password: |
| 921 | |
| 922 | 1. The tool asks g1t for a code and shows you a link and a short code such |
| 923 | as `WDJB-MJHT`. |
| 924 | 2. You open the link, sign in (or create an account), check that the code |
| 925 | matches, and approve. |
| 926 | 3. The tool collects its token. |
| 927 | |
| 928 | ```sh |
| 929 | # 1. The tool starts a sign-in. |
| 930 | curl -X POST https://api.g1t.sh/device/code -H "Content-Type: application/json" -d '{"client_name": "my-tool"}' |
| 931 | |
| 932 | # 2. You open verification_uri_complete from the response and approve. |
| 933 | |
| 934 | # 3. The tool polls, no faster than "interval" seconds, until it is approved. |
| 935 | curl -X POST https://api.g1t.sh/device/token -H "Content-Type: application/json" -d '{"device_code": "…"}' |
| 936 | ``` |
| 937 | |
| 938 | The poll answers with a `status` of `pending`, `approved`, `denied` or |
| 939 | `expired`. An approved answer carries the token, once. Codes expire after 15 |
| 940 | minutes. The token appears in |
| 941 | [Settings → Access tokens](https://g1t.sh/settings/tokens) under the tool's name, where you |
| 942 | can delete it. |
| 943 | |
| 944 | Only approve a code you asked for. The token has full access: it can do |
| 945 | everything you can. To give a tool less, make an |
| 946 | [access token](#create-a-fine-grained-token) with only the scopes it needs instead. |
| 947 | |
| 948 | ## Resetting your password |
| 949 | |
| 950 | Use [g1t.sh/forgot](https://g1t.sh/forgot) and enter any confirmed |
| 951 | address of your account. The link goes to that address and works for one |
| 952 | hour; your primary and backup addresses are told a reset was asked for |
| 953 | when it went elsewhere. A new account that has not confirmed its address |
| 954 | yet can use that address, and following the link confirms it. |
| 955 | |
| 956 | The page answers the same way whether or not the address has an account. |
| 957 | g1t sends at most 5 reset links an hour to one address. If g1t cannot |
| 958 | take the request at all, the page says so and keeps what you typed, so you |
| 959 | can try again. |
| 960 | |
| 961 | Setting a new password signs you out everywhere and emails your primary |
| 962 | and backup addresses. |
| 963 | |
| 964 | ## Too many attempts |
| 965 | |
| 966 | g1t counts wrong passwords, on the sign-in page, for git over HTTPS and |
| 967 | when confirming it is you, against the account and against where they come |
| 968 | from. After 10 wrong passwords for one account in an hour, or 30 from one |
| 969 | place, g1t stops checking passwords for it for a minute, then twice as long |
| 970 | after each further wrong password, up to an hour. While it waits, every |
| 971 | attempt gets the same answer: "Too many attempts". The account's primary |
| 972 | and backup addresses are told the first time. Signing in with the right |
| 973 | password, or resetting it, clears the count. Access tokens, SSH keys and |
| 974 | GitHub sign-in are not affected. |
| 975 | |
| 976 | ## Security log |
| 977 | |
| 978 | [Settings → Security log](https://g1t.sh/settings/security-log) lists what |
| 979 | happened to your account: addresses added, confirmed, removed or made |
| 980 | primary, your backup and privacy settings, password changes, pauses after |
| 981 | too many wrong passwords, two-factor authentication turned on or off and |
| 982 | recovery codes made or used, personal access tokens created, deleted or |
| 983 | given new scopes, SSH keys added or removed, and applications authorized, |
| 984 | changed or revoked. Changes g1t staff made, such as removing an address |
| 985 | someone else needed, say so and why. |
| 986 | |
| 987 | Token, SSH key, application and two-factor changes are also recorded in the |
| 988 | [audit log](/guides/audit-log/) of each workspace you belong to, where its |
| 989 | owners see them. |
| 990 | |
| 991 | ## Deleting your account |
| 992 | |
| 993 | You can delete your account from |
| 994 | [Settings → Account](https://g1t.sh/settings/account), signed in as |
| 995 | yourself. It is not gone at once: for **30 days** g1t keeps it, so that a |
| 996 | deletion you did not mean, or did not make, can be undone through support. |
| 997 | After 30 days it is removed for good. |
| 998 | |
| 999 | 1. Open **Settings → Account** and go to **Danger zone**. If anything is |
| 1000 | in the way, it says what, instead of offering the button. |
| 1001 | 2. Choose **Delete account**. The dialog lists what goes with it: your |
| 1002 | workspaces, the repositories you were added to, your access tokens, SSH |
| 1003 | keys and connected applications. |
| 1004 | 3. Type your username, and your password unless you signed in within the |
| 1005 | last 10 minutes. An account that signs in with GitHub only signs out, |
| 1006 | signs in with GitHub again, and deletes it within 10 minutes. |
| 1007 | 4. Choose **Delete account** again. You are signed out, and g1t emails your |
| 1008 | primary and backup addresses to say it was deleted. |
| 1009 | |
| 1010 | There is no API route or MCP tool for deleting an account, by design: like |
| 1011 | [creating one](#creating-an-account), it happens only in a browser, signed |
| 1012 | in as yourself, never with a token or as an agent. |
| 1013 | |
| 1014 | ### What stands in the way |
| 1015 | |
| 1016 | | | | |
| 1017 | | --- | --- | |
| 1018 | | A workspace you own alone | Each live workspace where you are the only owner is listed. [Make someone else an owner](/guides/workspaces/#change-someones-role) of it, or [delete it](/guides/workspaces/#delete-a-workspace), first. Deleting a workspace settles its billing, which can ask for something first: the list says what. A workspace you own with someone else is not in the way. | |
| 1019 | | A protected account | `g1t` and the other names g1t uses for itself can never be deleted, by anyone. | |
| 1020 | |
| 1021 | Billing belongs to workspaces, not to accounts, so once no workspace |
| 1022 | depends on you alone there is nothing for billing to settle. |
| 1023 | |
| 1024 | When g1t's staff delete an account, on its owner's request or for abuse, |
| 1025 | the workspaces it alone owns are not left without an owner. Staff either |
| 1026 | wait for another owner to be made, or delete those workspaces together |
| 1027 | with the account, each exactly as its owner would: its billing is settled |
| 1028 | first, everything in it goes with it, and it is kept 30 days for a |
| 1029 | restore like any deleted workspace. Its audit log records the deletion as |
| 1030 | g1t's staff. Staff never do this for a workspace whose billing cannot be |
| 1031 | settled yet (an unpaid invoice, prepaid credit, usage still being metered), |
| 1032 | or for one of the workspaces g1t protects; if any of them stands in the |
| 1033 | way, nothing is deleted. |
| 1034 | |
| 1035 | ### What happens |
| 1036 | |
| 1037 | At once, when you delete it: |
| 1038 | |
| 1039 | | | | |
| 1040 | | --- | --- | |
| 1041 | | Signing in | You are signed out everywhere. Signing in with your password, GitHub, a recovery code or from a tool fails, with the same answer a wrong password gets. | |
| 1042 | | Access tokens, SSH keys and applications | Your personal access tokens (classic and fine-grained), SSH keys, connected applications and sign-ins from a tool stop working and are removed, and so do the deploy keys you added to repositories. A workspace's own tokens are not affected, even ones you made. | |
| 1043 | | Workspaces, teams and repositories | You leave every workspace and team, and lose the roles you were given on single repositories. Repository invitations waiting for you are withdrawn, and invites you made that nobody used are revoked. | |
| 1044 | | Your profile | `g1t.sh/<username>` answers 404, and you drop out of search. Nobody can add you to a workspace, team or repository, and nothing more is emailed to you. | |
| 1045 | | What you wrote | Stays where it is, under your username for now. Commits made with your confirmed or noreply addresses show as `ghost`, and as yours again if your account is restored. | |
| 1046 | | Your username | Held for your account. Nobody else can take it. | |
| 1047 | |
| 1048 | Within 30 days, support can restore it: write to support@g1t.sh from one |
| 1049 | of its addresses. You come back to the workspaces, teams and repositories |
| 1050 | you were in, where they are still there, and sign in again with your |
| 1051 | password. Your old sessions, tokens and keys stay ended: make new ones. |
| 1052 | |
| 1053 | After 30 days it is removed for good: |
| 1054 | |
| 1055 | | | | |
| 1056 | | --- | --- | |
| 1057 | | Your addresses, keys and profile | Removed: your email addresses, two-factor secret and recovery codes, GitHub link, picture, profile and security log, and your inbox and its settings. | |
| 1058 | | What you wrote | Issues, pull requests, comments and reviews keep their place and their words, and show as written by `ghost`. You are taken off issues and pull requests you were assigned to or asked to review. Commits keep the name and address git recorded in them; those made with your [noreply address](#keeping-your-address-private) show as `ghost`. | |
| 1059 | | Workspaces you made | Name `ghost` as their creator. | |
| 1060 | | Statements, invoices and audit logs | Kept with your username, for the workspaces they belong to. | |
| 1061 | | Your username | Never given to another account or workspace, so links, mentions and remotes that use it keep meaning what they meant. `ghost` is reserved for this, and nobody can register it. | |
| 1062 | |
| 1063 | ## What g1t stores |
| 1064 | |
| 1065 | Passwords are stored as salted PBKDF2-SHA256 hashes. Sessions and tokens are |
| 1066 | stored as SHA-256 hashes. Neither can be read back. A two-factor secret is |
| 1067 | encrypted (AES-256-GCM) and bound to your account, and recovery codes are |
| 1068 | kept as SHA-256 hashes. |