Get started

Authentication

The Pentify API uses Bearer tokens. Every request must carry an Authorization: Bearer pk_* header.

GET /v1/usage HTTP/1.1
Host: api.pentify.io
Authorization: Bearer pk_live_4j7n9q2bv8rh3xk5p1m6t0w8d2

Key formats

Prefix	Mode	Use
`pk_live_*`	Production	Real workspaces, real billing. Default.
`pk_test_*`	Sandbox	Issued only against Stripe test mode tenants. Same shape, no real charges.

After the prefix is a 26-character base32 random secret. The full key is displayed exactly once when created. Pentify stores only a SHA-256 hash and the first 12 characters (the prefix) for display.

Workspace keys vs personal access tokens

Two scope types share the same pk_* format.

Type	Created by	Survives owner removal?	Best for
Workspace key	Workspace Admin	Yes	CI/CD, scripts, production integrations.
Personal access token	Any member	No — auto-revoked when the user leaves	Local dev, exploration.

Both types deduct from the same shared workspace token balance. PATs do not create a separate billing surface.

Scopes

Scope	Allows
`scans:read`	List, retrieve scans, read findings, fetch reports.
`scans:write`	Create and cancel scans.
`targets:read`	List and retrieve targets.
`targets:write`	Register and verify targets.
`reports:read`	Read JSON reports, download PDFs.
`webhooks:write`	Manage webhook subscriptions.
`usage:read`	Read token balance and usage breakdown.

A request with an insufficient scope returns 403 insufficient_scope. See Errors.

Setting up the client

import { Pentify } from "@pentify/sdk";

const pentify = new Pentify({ apiKey: process.env.PENTIFY_API_KEY! });

Rotation

Pentify does not auto-rotate keys. Rotation is a two-step process:

Create a new key with the same scopes.
Roll the new value into your secret store, redeploy, then revoke the old key from Settings → API keys.

Leaked key?

Revoke first, regenerate second. Revocation is immediate and irreversible.

Revocation

Revocation is immediate. Subsequent requests with the revoked key return 401 invalid_api_key. Revocation is irreversible — generate a new key.