Authentication & Security

Every request uses JWT tokens you sign and control. Generate short-lived tokens for CI/CD, long-lived tokens for development, and manage permissions with fine-grained scopes—no third-party authentication required.

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

Scope	Description	Operations
git:read	Read repository contents	clone, fetch, pull
git:write	Modify repository	push (includes read)
repo:write	Create repositories	POST /api/v1/repos
org:read	List repositories	GET /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:

TypeScript

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.