API reference

Use the control API for package metadata, publishing, grants, tokens, policy, and audit.

The API is JSON over HTTP except for tarball publishing, which uses multipart/form-data. Package installation uses the npm-compatible registry endpoints.

Control API

https://api.preview.packagepass.dev/v1

Registry

https://registry.preview.packagepass.dev/npm/

Authentication

headers

Authorization: Bearer <packagepass-token>
Accept: application/json
X-PackagePass-Tenant: acme

Tenant resolution

Most tenant-scoped endpoints resolve the tenant from tenantId, X-PackagePass-Tenant, or the principal attached to the token.

Response envelope

success

{
  "data": {
    "id": "pkg_...",
    "name": "@acme/payments"
  },
  "requestId": "req_..."
}

error

{
  "error": {
    "code": "forbidden",
    "message": "No matching grant.",
    "details": {}
  },
  "requestId": "req_..."
}

Log requestId

Every response includes a request ID, and the server also returns it as x-request-id. Keep it with failed publish, install, policy, and token operations.

Packages

Create package metadata

Packages must use scoped npm names. Creating a package requires package:publish on the tenant.

POST /v1/packages

curl -X POST "https://api.preview.packagepass.dev/v1/packages" \
  -H "authorization: Bearer $PACKAGEPASS_API_KEY" \
  -H "x-packagepass-tenant: acme" \
  -H "content-type: application/json" \
  -d '{
    "name": "@acme/payments",
    "description": "Customer payments SDK"
  }'

Publish a release tarball

POST /v1/packages/:package/versions

curl -X POST "https://api.preview.packagepass.dev/v1/packages/%40acme%2Fpayments/versions" \
  -H "authorization: Bearer $PACKAGEPASS_API_KEY" \
  -F 'tag=latest' \
  -F 'manifest={"name":"@acme/payments","version":"4.8.0","type":"module"}' \
  -F "tarball=@acme-payments-4.8.0.tgz;type=application/octet-stream"

manifest

JSON package manifest. name must match the route package and version must be semver-compatible.

tarball

The .tgz artifact uploaded as a file part.

tag

Optional dist-tag. Defaults to latest.

Publish a preview tarball

POST /v1/packages/:package/previews

curl -X POST "https://api.preview.packagepass.dev/v1/packages/%40acme%2Fpayments/previews" \
  -H "authorization: Bearer $PACKAGEPASS_API_KEY" \
  -F 'channel=pr-482' \
  -F 'manifest={"name":"@acme/payments","version":"4.8.0","type":"module"}' \
  -F "tarball=@acme-payments-pr-482.tgz;type=application/octet-stream"

Preview publishes generate or accept a preview version, set the dist-tag preview-<channel>, and return install commands.

Access

Create a grant

Grants are the authorization records used by the API and registry. Creating grants requires grant:manage on the target resource.

POST /v1/grants

curl -X POST "https://api.preview.packagepass.dev/v1/grants" \
  -H "authorization: Bearer $PACKAGEPASS_API_KEY" \
  -H "x-packagepass-tenant: acme" \
  -H "content-type: application/json" \
  -d '{
    "subject": { "type": "customer", "slug": "globex" },
    "resource": { "type": "package", "name": "@acme/payments" },
    "actions": ["package:install"],
    "conditions": {
      "expiresAt": "2026-05-26T00:00:00.000Z"
    }
  }'

Common schemas

Schema	Shape
`SubjectRef`	`{ "type": "user", "email": "alice@example.com" }`, `{ "type": "customer", "slug": "globex" }`, `{ "type": "agent", "slug": "release", "kind": "ci" }`
`ResourceRef`	`{ "type": "tenant", "slug": "acme" }`, `{ "type": "scope", "name": "@acme" }`, `{ "type": "package", "name": "@acme/payments" }`, `{ "type": "package_version", "name": "@acme/payments", "version": "4.8.0" }`
`GrantInput`	tenantId, subject, resource, actions, and optional conditions. The current policy engine enforces expiresAt; other condition fields are stored as metadata.
`TokenCreateInput`	tenantId, name, subject, optional resources with actions, and optional expiresAt.
`RegistryPackage`	id, tenantId, scopeId, name, slug, description, readme, distTags, archivedAt, createdAt, and updatedAt.
`RegistryVersion`	id, tenantId, packageId, packageName, version, kind, status, manifest, tarball, provenance, deprecatedMessage, and createdAt.

Create an install token

POST /v1/tokens/install

curl -X POST "https://api.preview.packagepass.dev/v1/tokens/install" \
  -H "authorization: Bearer $PACKAGEPASS_API_KEY" \
  -H "x-packagepass-tenant: acme" \
  -H "content-type: application/json" \
  -d '{
    "name": "globex payments install",
    "subject": { "type": "customer", "slug": "globex" },
    "resources": [{
      "type": "package",
      "name": "@acme/payments",
      "actions": ["package:install"]
    }],
    "expiresAt": "2026-05-26T00:00:00.000Z"
  }'

Endpoint reference

Identity

Method	Path	Purpose
`GET`	`/v1/me`	Return the authenticated principal.

Tenants and scopes

Method	Path	Purpose
`POST`	`/v1/tenants`	Create a tenant.
`GET`	`/v1/tenants`	List tenants.
`POST`	`/v1/scopes`	Create a scope such as @acme.
`GET`	`/v1/scopes`	List scopes for the active tenant.

Packages

Method	Path	Purpose
`POST`	`/v1/packages`	Create package metadata.
`GET`	`/v1/packages`	List packages.
`GET`	`/v1/packages/:package`	Read package metadata.
`PATCH`	`/v1/packages/:package`	Update description or readme.
`POST`	`/v1/packages/:package/archive`	Archive a package.

Versions and previews

Method	Path	Purpose
`POST`	`/v1/packages/:package/versions`	Publish a release tarball with multipart/form-data.
`GET`	`/v1/packages/:package/versions`	List versions.
`GET`	`/v1/packages/:package/versions/:version`	Read one version.
`POST`	`/v1/packages/:package/versions/:version/deprecate`	Deprecate a version.
`POST`	`/v1/packages/:package/versions/:version/yank`	Yank a version.
`POST`	`/v1/packages/:package/previews`	Publish a preview tarball to preview-<channel>.
`GET`	`/v1/packages/:package/previews`	List preview versions.

Dist-tags

Method	Path	Purpose
`GET`	`/v1/packages/:package/dist-tags`	Read dist-tags.
`PUT`	`/v1/packages/:package/dist-tags/:tag`	Point a tag at a version.
`DELETE`	`/v1/packages/:package/dist-tags/:tag`	Remove a tag.

Access control

Method	Path	Purpose
`POST`	`/v1/grants`	Create a grant.
`GET`	`/v1/grants`	List grants.
`DELETE`	`/v1/grants/:grantId`	Revoke a grant.
`POST`	`/v1/policy/explain`	Explain an authorization decision.

Subjects and tokens

Method	Path	Purpose
`POST`	`/v1/customers`	Create a customer subject.
`GET`	`/v1/customers`	List customer subjects.
`POST`	`/v1/agents`	Create an agent subject.
`GET`	`/v1/agents`	List agent subjects.
`GET`	`/v1/agents/:agent`	Read an agent subject.
`PATCH`	`/v1/agents/:agent`	Update an agent subject.
`DELETE`	`/v1/agents/:agent`	Delete an agent and clean up direct access, tokens, and memberships.
`POST`	`/v1/groups`	Create a group subject.
`GET`	`/v1/groups`	List group subjects.
`GET`	`/v1/groups/:group`	Read a group subject and its members.
`PATCH`	`/v1/groups/:group`	Update a group subject.
`DELETE`	`/v1/groups/:group`	Delete a group and clean up direct access, tokens, and memberships.
`POST`	`/v1/tokens/api`	Mint an API token.
`POST`	`/v1/tokens/install`	Mint an install token.
`POST`	`/v1/tokens/ci/exchange`	Exchange a CI identity token.
`GET`	`/v1/tokens`	List tokens.
`DELETE`	`/v1/tokens/:tokenId`	Revoke a token.

Utilities

Method	Path	Purpose
`POST`	`/v1/install-config`	Generate .npmrc or bunfig.toml content.
`GET`	`/v1/audit-events`	List audit events.
`POST`	`/v1/validate/package`	Validate package.json against PackagePass policy.

Registry endpoints

Endpoint	Purpose
`GET /npm/-/ping`	Registry health check.
`GET /npm/-/whoami`	Return the package-install principal for the current token.
`GET /npm/:encodedPackage`	Return an npm packument for an authorized package.
`GET /npm/:encodedPackage/-/:tarball`	Download an authorized tarball.
`HEAD /npm/:encodedPackage/-/:tarball`	Check tarball availability without downloading it.

Registry package and tarball requests require package:install. Unauthorized packages and tarballs are returned as 404 to avoid leaking package names.

Package policy

Required

Scoped package name, semver-compatible version, and a manifest name that matches the route package.

Blocked by default

Lifecycle scripts such as postinstall, binaries, and bundled dependencies are blocked for generated TypeScript libraries.

Action names

package:read

package:install

package:publish

package:deprecate

package:yank

package:manage_dist_tags

grant:manage

token:mint

audit:read