Tokens

Every programmatic call to githosted uses a token. There are two kinds, two permissions, and an expiry you choose. Pick the narrowest that does the job.

Two kinds

Workspace tokens (gw_…) can see every repo in their workspace and create new repos there. Reach for these when an agent or app needs to manage many repos in the same workspace — e.g. one repo per session.

Repo tokens (gr_…) are scoped to specific repos in their workspace, listed when the token is created. Reach for these when a token only needs to touch a known set of repos.

Two permissions

Permission	Can read files / log / diff	Can write / push
read	yes	no
write	yes	yes

Read-only tokens are great for sandbox environments that consume a repo but shouldn’t be able to mutate it.

Expiry

Pick a TTL when you create the token: 7 days, 30 days, 90 days, 1 year, or no expiry. Shorter is better — leaked credentials with short windows are less expensive incidents.

The token’s expiry is reflected in metadata so the SDK can tell the difference between no token and expired token and surface a useful error.

How tokens are used

Every authenticated call attaches the token as either:

• An HTTP Authorization: Bearer <token> header (the SDK does this automatically)
• HTTP Basic auth where the token is the password and the username is anything (git clients use this style)

Both work everywhere; pick whichever your client prefers. The SDK auto-reads GITHOSTED_TOKEN from the environment if you don’t pass one explicitly.

How tokens are stored

Server-side, tokens are stored as HMAC-SHA256(server_pepper, token) digests. We never store the original value. That’s why you only see the full gw_… / gr_… string once at creation time — the dashboard literally cannot show it again.

If you lose a token, revoke it and create a new one.