Skip to main content
All access to Code Storage requires JWT tokens signed by your organization. Each token:
  • Grants access to a single repository (except org:read tokens, which are org-wide)
  • Contains explicit permission scopes
  • Has a configurable time-to-live (TTL)
  • Is customer-signed for full control
The SDK helps simplify and automate the management of these tokens.

​
Token structure

{
  "iss": "your-org", // Your organization identifier
  "sub": "ci-pipeline-prod", // Agent identity (for logging)
  "repo": "team/project-alpha", // Repository access (omit for org-wide tokens)
  "scopes": ["git:read", "git:write"], // Permissions
  "iat": 1723453189, // Issued at (Unix timestamp)
  "exp": 1723456789 // Expiration (Unix timestamp)
}
SDK note: the client normalizes Git status codes in state to descriptive values and provides the original status under rawState alongside camelCase property names.
JWT headers must include: 
{
  "alg": "ES256", // Algorithm (ES256 or RS256 are supported)
  "typ": "JWT", // Type
}

​
Permission scopes

ScopeDescriptionOperations
git:readRead repository contentsclone, fetch, pull
git:writeModify repositorypush (includes read)
repo:writeCreate repositoriesPOST /api/v1/repos
org:readList repositoriesGET /api/v1/repos

​
Key management

Public keys for JWT verification are managed through the Pierre Admin Panel.

​
Manual JWT generation

For advanced scenarios—such as integrating with custom Git tooling or provisioning tokens outside the SDK clients—you can generate JWTs directly using your preferred JWT library (TypeScript) or the Python helper. They accept your PEM-encoded private key, repository URL (name), and desired scopes, then return a ready-to-use token: 
import { promises as fs } from 'node:fs';
import { importPKCS8, SignJWT } from 'jose';

// Load your private key from disk (PKCS8 PEM)
const keyPem = await fs.readFile('path/to/key.pem', 'utf8');
const key = await importPKCS8(keyPem, 'ES256');

const now = Math.floor(Date.now() / 1000);
const token = await new SignJWT({
  iss: 'your-name', // e.g., 'v0'
  sub: 'ci-pipeline-prod',
  repo: 'team/project-alpha',
  scopes: ['git:write', 'git:read'],
  iat: now,
  exp: now + 3600, // 1 hour
})
  .setProtectedHeader({ alg: 'ES256', typ: 'JWT' })
  .sign(key);

const gitUrl = `https://t:${token}@your-name.code.storage/team/project-alpha.git`;
console.log(`git clone ${gitUrl}`);
Parameters
  • keyPem / key_pem (required): Private key in PKCS8 PEM format. RSA and EC (P-256/384/521) keys are supported.
  • issuer (required): Customer identifier (for example your-name in HTTPS remotes).
  • repoId / repo_id (required): Repository ID (name) the token will access.
  • scopes (optional): Explicit permissions. Defaults to ["git:write", "git:read"]. Available scopes: git:read, git:write, repo:write.
  • ttl (optional): Token lifetime in seconds. Defaults to 31536000 (1 year).
The helper auto-detects the key type and signs with RS256 or ES256 as appropriate.