Token Management

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

Quickstart

import { Client } from "@githosted/sdk";

const client = new Client(); // workspace token (gw_)

// Create a read-only repo token
const result = await client.createToken({
  name: "ci-deploy",
  kind: "repo",
  permission: "read",
  repoAllowlist: ["deploy-configs"],
  ttlHours: 1,
});

console.log(result.token);        // "gr_xxxx..." — store this immediately
console.log(result.record.name);  // "ci-deploy"

API Reference

`client.createToken(options)`

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.

const result = await client.createToken({
  name: "my-token",              // required
  kind: "workspace",             // "workspace" (default) or "repo"
  permission: "write",           // "read" or "write" (default)
  repoAllowlist: ["my-repo"],   // only for kind: "repo"
  ttlHours: 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.listTokens(options?)`

List all tokens in the workspace.

const result = await client.listTokens();
for (const t of result.tokens) {
  console.log(`${t.prefix}_*** ${t.name} (${t.kind}, ${t.permission})`);
}

// Paginated
const page = await client.listTokens({ pageSize: 20 });

Each token includes: prefix, name, kind, permission, repoAllowlist, createdAt, expiresAt, revokedAt, lastUsedAt, createdByUserId, createdByName, createdByTokenPrefix.

Token Types

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

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

const result = await client.createToken({
  name: `ci-${jobId}`,
  kind: "repo",
  permission: "write",
  repoAllowlist: ["deploy-configs"],
  ttlHours: 1,
});
// Pass result.token to the CI job as an env var

Read-only dashboard token

const result = await client.createToken({
  name: "dashboard-readonly",
  kind: "repo",
  permission: "read",
  repoAllowlist: ["metrics", "deploy-configs"],
  ttlHours: 24 * 30, // 30 days
});