Token Management

Create and list tokens programmatically. Useful for provisioning scoped access for CI jobs, sandboxes, and dashboards.

Quickstart

from githosted import Client

client = Client()  # workspace token (gw_)

# Create a read-only repo token
result = client.create_token(
    "ci-deploy",
    kind="repo",
    permission="read",
    repo_allowlist=["deploy-configs"],
    ttl_hours=1,
)

print(result.token)        # "gr_xxxx..." — store this immediately
print(result.record.name)  # "ci-deploy"

API Reference

`client.create_token(name, *, kind, permission, repo_allowlist, ttl_hours)`

Create a new token in the workspace. Requires a workspace token (gw_) with write permission. The raw token string is only returned at creation time.

result = client.create_token(
    "my-token",                        # required
    kind="workspace",                  # "workspace" (default) or "repo"
    permission="write",                # "read" or "write" (default)
    repo_allowlist=["my-repo"],        # only for kind="repo"
    ttl_hours=24,                      # 0 = no expiration
)

result.token            # raw token string (gw_ or gr_ prefix)
result.record.prefix    # "gw" or "gr"
result.record.kind      # "workspace" or "repo"

`client.list_tokens(*, page_size, page_token)`

List all tokens in the workspace.

result = client.list_tokens()
for t in result.tokens:
    print(f"{t.prefix}_*** {t.name} ({t.kind}, {t.permission})")

# Paginated
page = client.list_tokens(page_size=20)

Each token includes: prefix, name, kind, permission, repo_allowlist, created_at, expires_at, revoked_at, last_used_at, created_by_user_id, created_by_name, created_by_token_prefix.

Token Types

Kind	Prefix	Access
`workspace`	`gw_`	All repos + control-plane calls
`repo`	`gr_`	Only repos in `repo_allowlist`

Workspace tokens can create both workspace and repo tokens. Repo tokens cannot create tokens or call control-plane endpoints.

Common Patterns

Short-lived tokens for CI

result = client.create_token(
    f"ci-{job_id}",
    kind="repo",
    permission="write",
    repo_allowlist=["deploy-configs"],
    ttl_hours=1,
)
# Pass result.token to the CI job as an env var

Read-only dashboard token

result = client.create_token(
    "dashboard-readonly",
    kind="repo",
    permission="read",
    repo_allowlist=["metrics", "deploy-configs"],
    ttl_hours=24 * 30,  # 30 days
)