Mint and revoke API Bearer tokens

An Inkpacket public API call is an org-scoped Bearer token, not a user session cookie. Owners and admins mint and revoke those secrets at /desk/settings#tokens. POST /api/orgs/tokens creates an ip_… value shown once. DELETE /api/orgs/tokens/:id revokes it. Inkpacket stores a SHA-256 tokenHash, not the plaintext. The list shows the prefix. That is the token-mint revoke loop.

Members cannot mint. Tokens never cross workspaces. GET /api/v1/health is public and does not take a Bearer token. Every /api/v1/packets and /api/v1/packets/:id* route requires Authorization: Bearer ip_…. A missing header returns 401 Bearer token required. A bad or revoked token returns 401 Invalid API token. Successful calls update lastUsedAt.

Creating envelopes from a template is create an envelope from a template via the API. Retries are Idempotency-Key on API sends. The longer developer guide is public API and signed webhooks. Desk help is Docs. This article is the secret itself: mint, copy, revoke.

Mint once, copy immediately

1. Sign in as owner or admin. Members see the Settings card and cannot create a token.
2. Open /desk/settings#tokens. The API section is /desk/settings#api.
3. Create a token. Copy the ip_… secret now. The desk will not show it again.
4. Send Authorization: Bearer ip_… on envelope routes. Watch lastUsedAt on the list after a successful call.

Ask Inkpacket for mint api token or open API tokens to open Settings. Those phrases stay on the product screen. If you lose the plaintext, revoke that row and mint another. There is no recover-plaintext control. Treating the prefix as the secret will 401.

What the 401s mean

• Bearer token required — the Authorization header is missing.
• Invalid API token — the secret is wrong, revoked, or belongs to another workspace.
• Not HTTP 402 ENVELOPE_LIMIT. That is a send that did not go out.
• The monthly send cap is HTTP 402 ENVELOPE_LIMIT, not a 429. Each API token allows 120 requests per minute per token. Over that limit, /api/v1 returns HTTP 429 with a Retry-After header. Inkpacket does not send X-RateLimit headers.

Access-code 429 is a PIN lockout on a signing page, not a token problem — access-code lockout recovery. Do not mint a second envelope because a worker got 401. Fix the header. Do not POST send again with a new Idempotency-Key to “retry auth.” That is a second envelope if the first send already succeeded.

Revoke on purpose

Revoke when a worker leaks, a contractor leaves, or you rotated a vault and the old secret must die. DELETE the id. In-flight workers fail on the next call with Invalid API token. Envelopes those workers already created stay on the desk. Revoke does not void envelopes. Revoke does not rotate signing links.

Mint a replacement before you revoke if the integration must not pause. Two tokens can exist. Use prefixes on the list to tell them apart. Do not share one secret across two organizations — tokens never cross workspaces, so that second tenant needs its own mint.

The click-path

1. Open Settings → API tokens as owner or admin.
2. Mint. Copy the ip_… secret into your vault in the same sitting.
3. Call GET /api/v1/packets with Authorization: Bearer ip_… and confirm lastUsedAt moves.
4. If the secret leaks, DELETE /api/orgs/tokens/:id, then mint a replacement.
5. Do not paste the plaintext into a ticket, a chat, or a public embed page.

Desk send still works without a token. Mint when a worker should create envelopes. If you only needed one send this afternoon, use the desk — API vs desk for ops teams.

What a token is not

• Not a webhook signing secret. Rotate that under Settings #webhooks.
• Not an embed URL. embedUrl is minted on send for one signer.
• Not a Web Form slug. Public fills do not use Bearer tokens.
• Not a Team invite. A teammate who should click the desk needs /desk/team#invite.

Implemented envelope routes sit next to send: list, create from a template, get, fill, replace fields, send, void, correct, resend. Send returns signingUrl, embedUrl, emailSent, and emailError. Listen for status on a webhook — listen for envelope status webhooks — instead of polling with a token you are about to revoke.

Caps and what is not open yet

Minting or revoking a token is not a send. The send that token later issues will count. Free allows 5 packets a month. Free at 5 packets a month is the live cap desk send, bulk rows, Web Form fills, and API send share. Hitting it returns HTTP 402 ENVELOPE_LIMIT. Starter is 20 envelopes — more than Free — plus 3 published Web Forms. Seat counts are planning numbers; invite does not refuse when a workspace is full.

Billing is published, not charging. Checkout is not open. Text-message (SMS) is coming soon. Drive missing: Drive not configured. Stripe off: Payments not live. None of those flags mint a Bearer secret. The FAQ and API on Features describe the same org-scoped token.

Mint. Copy once. Revoke the id when it leaks. Stay on that workspace. Then create one throwaway envelope from a template so lastUsedAt moves — open a workspace on Free — see published pricing — before a production worker depends on a secret you never stored.