flagon-io/g1t

public

1	---
2	title: Accounts and authentication
3	description: Accounts, invites, email addresses, confirming them, two-factor authentication and recovery codes, personal access tokens and their scopes, OAuth, signing in from a tool, password reset and your security log.
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	Accounts can only be created in a browser. There is no API for it, by
15	design: it keeps passwords out of scripts and agents, and lets g1t protect
16	the one place accounts are made.
17
18	## Your settings
19
20	Your own settings are at [g1t.sh/settings](https://g1t.sh/settings), one
21	page each. Open them from your account menu at the bottom of the sidebar,
22	under Your settings; the sidebar then lists every page.
23
24	\| Page \| Address \| What is on it \|
25	\| --- \| --- \| --- \|
26	\| Profile \| [`/settings/profile`](https://g1t.sh/settings/profile) \| Your picture, and your [public profile](/guides/workspaces/#profiles): name, pronouns, bio, location and website. \|
27	\| 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). \|
28	\| Invites \| [`/settings/invites`](https://g1t.sh/settings/invites) \| [Making, copying and revoking invites](#invites). \|
29	\| SSH keys \| [`/settings/keys`](https://g1t.sh/settings/keys) \| Public keys for [git over SSH](/guides/git/). \|
30	\| Access tokens \| [`/settings/tokens`](https://g1t.sh/settings/tokens) \| Your [personal access tokens](#access-tokens). \|
31	\| GitHub \| [`/settings/github`](https://g1t.sh/settings/github) \| [Linking and unlinking GitHub](/guides/github/#link-and-unlink-github). \|
32	\| 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. \|
33	\| Two-factor authentication \| [`/settings/two-factor`](https://g1t.sh/settings/two-factor) \| [An authenticator app and recovery codes](#two-factor-authentication). \|
34	\| Security log \| [`/settings/security-log`](https://g1t.sh/settings/security-log) \| [What happened to your account](#security-log). \|
35
36	`g1t.sh/settings` opens Profile.
37
38	## Signing in with GitHub
39
40	Continue with GitHub on the sign-in and sign-up pages signs you in with
41	your GitHub account, and makes a g1t account the first time. Link or
42	unlink GitHub in [Settings → GitHub](https://g1t.sh/settings/github). See
43	[GitHub](/guides/github/#sign-in-with-github).
44
45	Making an account with GitHub needs an invite too: start from your invite
46	link, or enter the code when g1t asks for it after GitHub.
47
48	With [two-factor authentication](#two-factor-authentication) on, signing in
49	with GitHub asks for a code from your app as well.
50
51	## Two-factor authentication
52
53	Two-factor authentication asks for a code from an authenticator app on
54	your phone each time you sign in with your password or with GitHub, so a
55	stolen password is not enough. Any app that reads a time-based one-time
56	password (TOTP) QR code works, such as 1Password, Google Authenticator or
57	Authy.
58
59	### Turn it on
60
61	1. Open [Settings → Two-factor authentication](https://g1t.sh/settings/two-factor)
62	and choose Set up. g1t asks for your password if you have not
63	signed in in the last 10 minutes.
64	2. Scan the QR code with your app, or type the key shown under it.
65	3. Enter the six-digit code the app shows, and choose Turn on.
66	4. Save the ten recovery codes g1t shows. They are shown only then.
67
68	### Signing in with it on
69
70	After your password (or GitHub), g1t asks for the code from your app. A
71	code works for 30 seconds, and the one before and after it are accepted
72	too, for a phone clock a little off. Each code works once. After five wrong
73	codes, or ten minutes, start the sign-in again.
74
75	Lost your phone? Enter a recovery code instead of the app's code. Each
76	works once, and your security log records its use.
77
78	Git over HTTPS never takes your password while two-factor authentication
79	is on: use a [personal access token](#access-tokens) as the password, or
80	[SSH](/guides/git/). Access tokens, SSH keys and OAuth applications are
81	not affected.
82
83	### Recovery codes, and turning it off
84
85	On the same page:
86
87	- Make new recovery codes replaces all ten; the old ones stop working.
88	- Turn off needs a code from your app or a recovery code, and your
89	password if you have not signed in in the last 10 minutes.
90
91	You cannot turn it off while you own a workspace that
92	[requires it](/guides/workspaces/#require-two-factor-authentication): stop
93	requiring it there first, or hand the workspace to another owner. In a
94	workspace that requires it, turning it off holds you out of that workspace
95	until you turn it on again.
96
97	Turning it on or off, and making new recovery codes, are emailed to your
98	primary and backup addresses, written to your [security log](#security-log),
99	and recorded in the [audit log](/guides/audit-log/) of each of your
100	workspaces as `two_factor.enabled` and `two_factor.disabled`.
101
102	### Require two-factor authentication
103
104	An owner can require it of everyone with access to a workspace. See
105	[Workspaces](/guides/workspaces/#require-two-factor-authentication).
106
107	Passkeys are not supported yet; they are next.
108
109	## Invites
110
111	While g1t is invite-only, every new account needs an invite code, such as
112	`g1t-k7m2-q9xd-…`. People already on g1t make them, and g1t sends them to
113	people who [asked for access](#asking-for-access). An invite:
114
115	- works once, for one new account;
116	- works for 30 days;
117	- when it was made for an email address, works only with that address;
118	- can be revoked by whoever made it until it is used.
119
120	### Using an invite
121
122	Every invite email links to `g1t.sh/invite/<code>`. That one page shows
123	who sent it and what it is for (joining a workspace, collaborating on a
124	repository, or just making an account), and finishes the job there:
125
126	1. No account yet: sign up on the page. When the invite was sent to
127	your address, the email field is filled in and locked, and the address
128	is confirmed already, so no confirmation email follows. Choose a
129	username (one is suggested from your address) and a password, or select
130	Continue with GitHub: the invite rides along, and the account uses
131	the invited address when GitHub has verified it too.
132	2. The address already has an account: select Sign in to accept.
133	After you sign in, the invite is accepted for you.
134	3. Signed in as someone else: an invite sent to one address works only
135	for an account that has confirmed that address. The page says so and
136	offers Sign out and continue.
137
138	Once the account exists or you have signed in, you land in the workspace
139	(or the repository) the invite was for, already a member, with a one-time
140	"You're in" banner, and it becomes the workspace your sidebar shows. A
141	code typed at [g1t.sh/register](https://g1t.sh/register) goes to the
142	same page.
143
144	An expired, revoked or used invite says which, and who sent it, so you
145	can ask them for a new one; or ask for access from the same page.
146
147	### Making invites
148
149	1. Open [Settings → Invites](https://g1t.sh/settings/invites).
150	2. Optionally enter the email address of the person you are inviting.
151	With one, g1t emails them the invite, and only that address can use it.
152	Without one, anyone with the link can, once.
153	3. Select Create invite, then copy the link.
154
155	Each person can have 5 invites out at a time. Pending and used invites
156	count; an invite you revoke, or one that expires before anyone uses it,
157	comes back to you. The list under the form shows each invite's state:
158	pending, joined (with the username of who joined), expired or revoked. You
159	must confirm your email before you can make invites. An agent's token and
160	a workspace's token cannot make them.
161
162	### Inviting someone into a workspace
163
164	An owner can invite an email address straight into a workspace from its
165	People page; see [members and roles](/guides/workspaces/#members-and-roles).
166	When the address has no g1t account, accepting makes the account and joins
167	the workspace in one step, and it uses one invite. Inviting someone who is
168	already on g1t costs nothing.
169
170	### Need more invites?
171
172	Write to [hey@flagon.io](mailto:hey@flagon.io?subject=%5Bg1t%20Invites%5D%20)
173	with the subject `[g1t Invites]` and say who you would like to bring. g1t
174	can give more invites to you, or to a workspace, whose owners then share
175	them. Invites given to a workspace appear under
176	[Settings → Invites](https://g1t.sh/settings/invites) for
177	each of its owners, as a choice of whose invites to use.
178
179	### Asking for access
180
181	Without an invite, [g1t.sh/register](https://g1t.sh/register) asks for your
182	email address and, if you like, what you will build. g1t emails that
183	address once to confirm you are on the list, and staff see the request
184	straight away. When they approve it, the invite comes to the same address,
185	sometimes with a note, and its link opens sign-up with the address filled
186	in. There is no fixed date: g1t opens up a few people at a time. Asking
187	again with the same address updates your request without another email; it
188	does not move you down the list.
189
190	### Invites through the API
191
192	\| Route \| MCP tool and action \| What it does \|
193	\| --- \| --- \| --- \|
194	\| [`GET /user/invites`](/reference/api/invites/list-invites/) \| `account` `list_invites` \| Your invites and how many you have left \|
195	\| [`POST /user/invites`](/reference/api/invites/create-invite/) \| `account` `create_invite` \| Make an invite, optionally for one `email` \|
196	\| [`DELETE /user/invites/{id}`](/reference/api/invites/revoke-invite/) \| `account` `revoke_invite` \| Revoke a pending invite \|
197	\| [`POST /workspaces/{workspace}/invitations`](/reference/api/invites/invite-member/) \| `workspace` `invite_member` \| Invite an address into a workspace. Owners only. \|
198
199	## Confirming your email
200
201	g1t sends a confirmation link from `noreply@g1t.sh`. It works for 24 hours.
202
203	Until you follow it you can sign in and look around, but you cannot create
204	repositories, push, or open issues and pull requests. Those requests fail with `403` and a
205	message telling you to confirm your address. To get a new link, sign in and
206	use the banner at the top of the site.
207
208	## Email addresses
209
210	An account can have up to 10 email addresses. Manage them in
211	[Settings → Emails](https://g1t.sh/settings/emails).
212
213	\| An address that is \| Can \|
214	\| --- \| --- \|
215	\| Primary \| Get account mail and password reset links. Exactly one, always confirmed once any address is. \|
216	\| Confirmed \| Sign you in (type it instead of your username), ask for a password reset, and mark commits that carry it as yours. \|
217	\| Backup \| Get security notices as well as the primary. Optional, and a confirmed address other than the primary. \|
218	\| Unconfirmed \| Nothing yet. It is not yours until you follow the link g1t sent it. \|
219
220	A confirmed address belongs to one account. Anyone can add an address they
221	have not confirmed; the first account to follow its link keeps it, and the
222	address leaves every other account that added it. An address another
223	account has confirmed cannot be added.
224
225	### Add an address
226
227	1. Open [Settings → Emails](https://g1t.sh/settings/emails).
228	2. Enter the address under Add an email address and select Add.
229	3. Follow the link g1t sends it. The link works for 24 hours; **Resend
230	link** sends a new one, at most once a minute and 10 times an hour.
231
232	If your account had no confirmed address yet, the first one you confirm
233	becomes your primary.
234
235	### Choose your primary and backup
236
237	Select Make primary beside a confirmed address. Under **Backup
238	address**, choose a confirmed address to get security notices too, or
239	Primary address only.
240
241	### Remove an address
242
243	Select Remove beside it. You cannot remove your primary address (make
244	another one primary first) or your last confirmed address.
245
246	### Confirming it is you
247
248	Adding or removing an address, changing your primary or backup, and
249	turning two-factor authentication on or off, need proof that it is you: a
250	sign-in in the last 10 minutes, or your password,
251	which g1t asks for on the page. After you enter it, g1t does not ask again
252	for 10 minutes. An account that signs in only with GitHub signs out and in
253	with GitHub again, or sets a password with
254	[Forgot your password](https://g1t.sh/forgot).
255
256	Each of these changes is emailed to every confirmed address on the account,
257	including an address that was just removed, and written to your
258	[security log](#security-log).
259
260	### Keeping your address private
261
262	Keep my email address private is on for every account unless you turn
263	it off. While it is on, commits g1t makes for you (merging a pull request
264	on the web, catching a branch up, and commits an agent makes for you) carry
265	your noreply address instead of your primary:
266
267	```
268	<8 characters of your account id>+<username>@users.noreply.g1t.sh
269	```
270
271	The page shows yours. It never receives mail. Turn the setting off to put
272	your primary address on those commits instead.
273
274	Block pushes that expose my email refuses a push that would publish one
275	of your addresses while you keep it private. When both settings are on,
276	g1t reads the new commits in each push you make, and declines the push if
277	any of them has one of your confirmed addresses as its author or committer
278	address. git shows why, with the address masked:
279
280	```
281	remote: push declined: commit 3f9a1c2 would publish s***@gmail.com while your email is private.
282	remote: Commit with 6c1d0efg+sam@users.noreply.g1t.sh (git config user.email 6c1d0efg+sam@users.noreply.g1t.sh) and amend,
283	remote: or change this in g1t.sh/settings/emails.
284	```
285
286	To push those commits:
287
288	1. Set your noreply address for the repository:
289	`git config user.email <your noreply address>`.
290	2. Rewrite the commits with it. For the last commit,
291	`git commit --amend --reset-author --no-edit`; for several,
292	`git rebase <base> --exec "git commit --amend --reset-author --no-edit"`.
293	3. Push again.
294
295	Only your own addresses are checked: commits by other people in the same
296	push go through, and so does your noreply address. A push an agent makes
297	for you follows your settings.
298
299	### How commits are attributed
300
301	g1t shows a commit as yours, with your picture and a link to your profile,
302	when its author address is one of your confirmed addresses or your noreply
303	address. Commits that g1t made for you before noreply addresses existed
304	(`<username>@users.g1t.sh`) count as yours too. An unconfirmed address
305	never attributes a commit, so nobody can claim your commits by adding your
306	address. Commits whose address matches no account show the name in the
307	commit.
308
309	### Email addresses through the API
310
311	\| Route \| MCP tool and action \| What it does \|
312	\| --- \| --- \| --- \|
313	\| [`GET /user/emails`](/reference/api/accounts/list-emails/) \| `account` `list_emails` \| Your addresses and email settings \|
314	\| [`POST /user/emails`](/reference/api/accounts/add-email/) \| `account` `add_email` \| Add an address; takes `email` and `password` \|
315	\| [`DELETE /user/emails/{email}`](/reference/api/accounts/remove-email/) \| `account` `remove_email` \| Remove an address; takes `password` \|
316	\| [`PATCH /user/email-settings`](/reference/api/accounts/update-email-settings/) \| `account` `update_email_settings` \| Change `primary`, `backup`, `private_email` or `block_private_pushes` \|
317
318	Through the API, `password` is the proof a sensitive change needs. Without
319	it, or with the wrong one, the answer is `403` with the code
320	`reauth_required`. Only a person's own token can use these: an agent's
321	token and a workspace's token are refused.
322
323	## Workspaces
324
325	Your account does not own repositories itself: a workspace does. After
326	confirming your email, the first thing you do is create one. Workspaces,
327	their members and roles, and the access tokens that belong to a workspace
328	are covered in [workspaces](/guides/workspaces/).
329
330	## Access tokens
331
332	A token stands in for your password everywhere outside the website:
333
334	\| Where \| How to send it \|
335	\| --- \| --- \|
336	\| git \| As the password, with your username. \|
337	\| API \| `Authorization: Bearer g1t_…` \|
338	\| MCP \| The same header, set when you add the server. \|
339
340	A token is shown once, when it is created; g1t stores only a hash of it.
341	If you lose one, delete it and create another. Delete a token the moment
342	you think someone else has seen it.
343
344	A token reaches everything you can reach, and its [scopes](#scopes) say
345	what it may do there. Give each token only the scopes the thing using it
346	needs.
347
348	For CI and integrations that work for a team, a workspace can have tokens
349	of its own that act as the workspace and keep working when their creator
350	leaves. See [workspace tokens](#workspace-tokens).
351
352	### Create a token
353
354	1. Open [Settings → Access tokens](https://g1t.sh/settings/tokens).
355	2. Under New token, give it a Name after what will use it.
356	3. Choose when it Expires: 7 days, 30 days, 90 days (the default),
357	1 year, or No expiry. An expired token stops working; make a new one.
358	No expiry shows a warning: the token works until someone deletes it.
359	4. Under Scopes, tick the boxes for what it may do. They are grouped
360	by area. The form starts on the Agent [preset](#presets); select
361	another preset to tick its boxes instead.
362	5. Select Create token, and copy the token. It is not shown again.
363
364	The list shows each token's name, when it was made and last used, when it
365	expires, and its access: a preset's name, its scopes, or Full access. To
366	change what a token may do, select Edit access, tick or untick boxes,
367	and select Save access. The token stays the same; the change applies
368	from its next request.
369
370	## Scopes
371
372	A scope is a resource and a level, written `resource:level`, such as
373	`issues:write`. A higher level includes the lower ones of the same
374	resource: `repo:admin` includes `repo:write`, which includes `repo:read`.
375	It never includes another resource: `repo:admin` does not let a token push,
376	which is `code:write`.
377
378	On the form, scopes are a checklist grouped by area:
379
380	\| Group \| Scopes \|
381	\| --- \| --- \|
382	\| Repositories & code \| `repo:read`, `repo:write`, `code:read`, `code:write` \|
383	\| Packages \| `packages:read`, `packages:write` \|
384	\| Issues & pull requests \| `issues:read`, `issues:write`, `pull_requests:read`, `pull_requests:write` \|
385	\| Agents \| `agents:run` \|
386	\| Workflows \| `workflows:read`, `workflows:write` \|
387	\| Checks \| `checks:read`, `checks:write` \|
388	\| Deployments \| `deployments:read`, `deployments:write` \|
389	\| Memory & search \| `memory:read`, `memory:write` \|
390	\| Account \| `account:read`, `account:write` \|
391	\| Notifications \| `notifications:read`, `notifications:write` \|
392	\| Security \| `security:read`, `security:write` \|
393	\| Workspace \| `workspace:read`, `access:read`, `webhooks:read`, `secrets:read` \|
394	\| Billing \| `billing:read`, `billing:write` \|
395	\| Runners \| `runners:read` \|
396	\| AI Gateway \| `models:read`, `models:write` \|
397	\| Dangerous \| `repo:admin`, `packages:delete`, `workspace:admin`, `access:admin`, `webhooks:admin`, `secrets:admin`, `runners:admin` \|
398
399	Ticking a higher level ticks the lower ones of its resource and greys
400	them out: tick `issues:write` and `issues:read` is ticked too. Untick
401	`issues:write` and `issues:read` stays ticked.
402
403	\| Scope \| What it lets a token do \|
404	\| --- \| --- \|
405	\| `repo:read` \| See repositories, their settings, labels, timelines, releases, languages, contributors and security alerts, and search \|
406	\| `repo:write` \| Create repositories, rename branches, change how pull requests merge and publish releases \|
407	\| `repo:admin` \| Rename, archive, transfer, delete or change who can see a repository, and dismiss security alerts \|
408	\| `code:read` \| Clone and fetch private repositories with git \|
409	\| `code:write` \| Push commits with git \|
410	\| `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 \|
411	\| `security:write` \| Dismiss and reopen alerts, bypass push protection, review bypass requests, manage custom patterns, upload SARIF and change security settings \|
412	\| `packages:read` \| Pull container images and install private [packages](/guides/packages/). Public ones need no scope. \|
413	\| `packages:write` \| Push container images and publish packages \|
414	\| `packages:delete` \| Delete packages and their versions \|
415	\| `issues:read` \| Read issues, comments and plans \|
416	\| `issues:write` \| Open, edit, close and comment on issues \|
417	\| `pull_requests:read` \| Read pull requests, their changes, sessions and merge queues \|
418	\| `pull_requests:write` \| Open, review, close and merge pull requests \|
419	\| `agents:run` \| Put g1t to work and message it, which uses the workspace's money \|
420	\| `workflows:read` \| Read workflows, runs and logs \|
421	\| `workflows:write` \| Run, cancel, rerun and turn workflows on or off \|
422	\| `checks:read` \| Read commits' statuses, check runs, check suites and annotations \|
423	\| `checks:write` \| Report [statuses and check runs](/guides/checks/) on commits, and ask for checks to run again \|
424	\| `deployments:read` \| See [deployments](/guides/deployments-api/), their statuses and environments \|
425	\| `deployments:write` \| Report deployments and their statuses, from any CI \|
426	\| `memory:read` \| Recall memory and search the workspace's context \|
427	\| `memory:write` \| Save memory for the next agent \|
428	\| `account:read` \| Read your email addresses, invites, invitations, pinned projects and stars \|
429	\| `account:write` \| Change your email addresses, make invites, answer invitations, pin projects and star repositories \|
430	\| `notifications:read` \| See your [inbox](/guides/inbox/), its threads, and what you subscribe to and watch \|
431	\| `notifications:write` \| Mark notifications read, done, saved or snoozed, subscribe to threads and watch repositories \|
432	\| `workspace:read` \| Read workspace settings, invites, integrations, model routes and [teams](/guides/teams/) \|
433	\| `workspace:admin` \| Create and delete workspaces, invite members, manage teams, connect integrations \|
434	\| `billing:read` \| See a workspace's [usage, budget, AI credit and invoices](/guides/usage-and-billing/) \|
435	\| `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. \|
436	\| `access:read` \| See who has access to repositories \|
437	\| `access:admin` \| Give people and teams access to repositories, and take it away \|
438	\| `webhooks:read` \| See webhooks and their deliveries \|
439	\| `webhooks:admin` \| Create, change and delete webhooks \|
440	\| `secrets:read` \| List secrets (never their values) and read variables \|
441	\| `secrets:admin` \| Set and delete secrets and variables \|
442	\| `runners:read` \| See [self-hosted runners](/guides/self-hosted-runners/), their groups and where agents run. Not in the Agent preset. \|
443	\| `runners:admin` \| Register and remove self-hosted runners, change their groups and settings \|
444	\| `models:read` \| See the workspace's [AI Gateway](/guides/ai-gateway/) requests: their models, tokens, cost and status \|
445	\| `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. \|
446
447	Every operation of the API and the MCP server needs exactly one of these,
448	except `whoami` (`GET /user`), which any token may use. Each endpoint's page
449	in the [API reference](/reference/api/) names its scope, and so does each
450	action in [MCP tools](/reference/mcp/). A few calls need a second scope for
451	what they ask:
452
453	\| Call \| Also needs \|
454	\| --- \| --- \|
455	\| `delegate` (`POST /repos/{owner}/{name}/issues/delegate`, the `agent` tool's `delegate`), which opens an issue \| `issues:write`, beside `agents:run` \|
456	\| `apply_plan` or `import_issue` (the `plan` tool's `apply`, the `issue` tool's `import`) with `assign: true` \| `agents:run` \|
457	\| `update_repo` with `private` or `default_branch` \| `repo:admin` \|
458
459	### What a token can do
460
461	What a request may do is where two things overlap:
462
463	1. Your role. A token reaches every workspace and repository you can,
464	including ones you join later, and never does more there than you could
465	on the website. A token with `repo:admin` still cannot delete a
466	repository unless you are an owner of its workspace. See
467	[access and roles](/guides/access-and-roles/).
468	2. Its scopes. What kinds of thing it may do.
469
470	To keep a token away from a workspace, use a
471	[workspace token](#workspace-tokens) instead: it reaches only its own
472	workspace.
473
474	### Presets
475
476	A preset ticks a starting set of boxes. Select one, then tick or untick
477	any box.
478
479	\| Preset \| Scopes \|
480	\| --- \| --- \|
481	\| Read only \| Every `read` scope. Changes nothing. \|
482	\| 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. \|
483	\| 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. \|
484	\| Full access \| Everything you can do, including deleting repositories and changing who has access. Marked Dangerous. \|
485
486	Admin scopes change things that are hard to undo, or decide who can reach
487	what. They are under Dangerous, with a warning. Give them only to
488	something you trust as much as yourself.
489
490	### Git and scopes
491
492	Over HTTPS, git checks the same token:
493
494	\| To \| Needs \|
495	\| --- \| --- \|
496	\| Clone or fetch a public repository \| No scope \|
497	\| Clone or fetch a private repository \| `code:read` \|
498	\| Push \| `code:write` \|
499
500	Your role on the repository applies too, as on the website. A refused push
501	or clone says which scope is missing.
502
503	### When a token lacks a scope
504
505	The API answers `403` with the scope that was missing in `needed_scope`:
506
507	```json
508	{
509	"error": {
510	"code": "forbidden",
511	"message": "This access token needs the issues:write scope to use create_issue.",
512	"needed_scope": "issues:write"
513	}
514	}
515	```
516
517	Through MCP the same message comes back as a tool result with `isError`
518	set. Give the token that scope with Edit access, or make a new token.
519
520	### Tokens made before scopes
521
522	Tokens and OAuth sign-ins made before tokens had scopes keep full access,
523	so nothing that uses them stops working. Settings marks each one
524	Legacy · full access, and says to narrow it to what it needs. For a
525	token, select Narrow this token; for an application, Change access
526	in [Connected applications](https://g1t.sh/settings/applications). Then
527	tick its scopes. A token you make with Full access on purpose is not marked
528	legacy.
529
530	A token from [signing in from a tool](#signing-in-from-a-tool), such as the
531	g1t CLI, has full access.
532
533	### Workspace tokens
534
535	A workspace's own tokens act as the workspace rather than a person. An
536	owner makes them in the workspace's Settings → Access tokens, with the
537	same checklist and expiry choices; the form starts on the CI preset. A
538	workspace token reaches all of that workspace's repositories, never
539	another workspace, and cannot manage people, tokens or workspaces. See
540	[workspace access tokens](/guides/workspaces/#workspace-access-tokens).
541
542	## Signing in with OAuth
543
544	Applications that can open your browser, such as an agent connecting to the
545	[MCP server](/guides/bring-your-own-agent/), sign you in with OAuth 2.1.
546	You see a page on g1t naming the application and where it will send you
547	back, and you approve or deny. The application never sees your password and
548	there is no token to copy.
549
550	The page lists what the application will be able to do, as the same
551	checklist a token has, with only the scopes it asked for, all ticked.
552	Untick anything you would rather it could not do, leaving at least one;
553	you cannot give it more than it asked for. Like a token, it reaches
554	everything you can.
555
556	An application that asks for no scopes in particular gets the
557	[Agent preset](#presets): every `read` scope except `runners:read`, and `code:write`,
558	`issues:write`, `pull_requests:write`, `agents:run`, `memory:write` and
559	`notifications:write`.
560	It never gets an admin scope unless it asks for one and you leave it
561	ticked.
562
563	Applications you have approved are listed in
564	[Settings → Connected applications](https://g1t.sh/settings/applications),
565	each with its access. Select Change access to tick or untick its
566	scopes, then Save access: it stays signed in, the change applies at
567	once, and its next refresh keeps it. Select Sign out to end its access
568	at once.
569
570	For people building a client:
571
572	\| \| \|
573	\| --- \| --- \|
574	\| Metadata \| `https://api.g1t.sh/.well-known/oauth-authorization-server` \|
575	\| Authorization \| `https://g1t.sh/oauth/authorize` \|
576	\| Token \| `https://api.g1t.sh/oauth/token` \|
577	\| Registration \| `https://api.g1t.sh/oauth/register` \|
578
579	- The flow is authorization code with PKCE. `S256` is required.
580	- Clients are public: there are no client secrets.
581	- Register with `client_name` and `redirect_uris`. A redirect address is an
582	`https` URL, `http` on `localhost`, or the application's own scheme. A
583	client on `localhost` may use any port.
584	- Registration stores nothing. The client id it returns encodes what was
585	registered, so it cannot be used to fill g1t with junk.
586	- Ask for scopes with `scope` on the authorization request, separated by
587	spaces, such as `scope=repo:read issues:write pull_requests:write`.
588	Names g1t does not know are left out. Leave `scope` out for the Agent
589	preset. The authorization server's metadata and
590	`https://mcp.g1t.sh/.well-known/oauth-protected-resource` list every
591	scope in `scopes_supported`.
592	- The token response's `scope` holds the scopes the person granted,
593	separated by spaces, or `*` for a sign-in with full access. Refreshing
594	keeps them.
595	- An access token lasts 30 days. The refresh token returned with it works
596	once and returns the next pair; the previous access token stops working.
597	- An authorization code lasts five minutes and works once.
598
599	## Signing in from a tool
600
601	A tool that cannot receive a redirect, such as a script on a remote machine,
602	gets a token without ever handling your password:
603
604	1. The tool asks g1t for a code and shows you a link and a short code such
605	as `WDJB-MJHT`.
606	2. You open the link, sign in (or create an account), check that the code
607	matches, and approve.
608	3. The tool collects its token.
609
610	```sh
611	# 1. The tool starts a sign-in.
612	curl -X POST https://api.g1t.sh/device/code -H "Content-Type: application/json" -d '{"client_name": "my-tool"}'
613
614	# 2. You open verification_uri_complete from the response and approve.
615
616	# 3. The tool polls, no faster than "interval" seconds, until it is approved.
617	curl -X POST https://api.g1t.sh/device/token -H "Content-Type: application/json" -d '{"device_code": "…"}'
618	```
619
620	The poll answers with a `status` of `pending`, `approved`, `denied` or
621	`expired`. An approved answer carries the token, once. Codes expire after 15
622	minutes. The token appears in
623	[Settings → Access tokens](https://g1t.sh/settings/tokens) under the tool's name, where you
624	can delete it.
625
626	Only approve a code you asked for. The token has full access: it can do
627	everything you can. To give a tool less, make an
628	[access token](#create-a-token) with only the scopes it needs instead.
629
630	## Resetting your password
631
632	Use [g1t.sh/forgot](https://g1t.sh/forgot) and enter any confirmed
633	address of your account. The link goes to that address and works for one
634	hour; your primary and backup addresses are told a reset was asked for
635	when it went elsewhere. A new account that has not confirmed its address
636	yet can use that address, and following the link confirms it.
637
638	The page answers the same way whether or not the address has an account.
639	g1t sends at most 5 reset links an hour to one address. If g1t cannot
640	take the request at all, the page says so and keeps what you typed, so you
641	can try again.
642
643	Setting a new password signs you out everywhere and emails your primary
644	and backup addresses.
645
646	## Too many attempts
647
648	g1t counts wrong passwords, on the sign-in page, for git over HTTPS and
649	when confirming it is you, against the account and against where they come
650	from. After 10 wrong passwords for one account in an hour, or 30 from one
651	place, g1t stops checking passwords for it for a minute, then twice as long
652	after each further wrong password, up to an hour. While it waits, every
653	attempt gets the same answer: "Too many attempts". The account's primary
654	and backup addresses are told the first time. Signing in with the right
655	password, or resetting it, clears the count. Access tokens, SSH keys and
656	GitHub sign-in are not affected.
657
658	## Security log
659
660	[Settings → Security log](https://g1t.sh/settings/security-log) lists what
661	happened to your account: addresses added, confirmed, removed or made
662	primary, your backup and privacy settings, password changes, pauses after
663	too many wrong passwords, two-factor authentication turned on or off and
664	recovery codes made or used, personal access tokens created, deleted or
665	given new scopes, SSH keys added or removed, and applications authorized,
666	changed or revoked. Changes g1t staff made, such as removing an address
667	someone else needed, say so and why.
668
669	Token, SSH key, application and two-factor changes are also recorded in the
670	[audit log](/guides/audit-log/) of each workspace you belong to, where its
671	owners see them.
672
673	## What g1t stores
674
675	Passwords are stored as salted PBKDF2-SHA256 hashes. Sessions and tokens are
676	stored as SHA-256 hashes. Neither can be read back. A two-factor secret is
677	encrypted (AES-256-GCM) and bound to your account, and recovery codes are
678	kept as SHA-256 hashes.