Authentication
Send Authorization: Bearer ip_… on the packet routes below. Owners and admins mint the token in Settings. The secret is shown once. Inkpacket stores a hash, not the plaintext.
A missing header returns 401 Bearer token required. A bad or revoked token returns 401 Invalid API token. Tokens do not cross workspaces.
GET /api/v1/health is public and does not take a Bearer token.
Rate limits
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.
The monthly packet cap is a different guard. Send volume over the plan limit returns HTTP 402 ENVELOPE_LIMIT, not 429. An access-code 429 is a signer PIN lockout, not this token limit.
Endpoints
- GET /api/v1/healthpublic
- GET /api/v1/packetsBearer token
- POST /api/v1/packetsBearer token
- GET /api/v1/packets/:idBearer token
- POST /api/v1/packets/:id/fillBearer token
- PUT /api/v1/packets/:id/fieldsBearer token
- POST /api/v1/packets/:id/sendBearer token
- POST /api/v1/packets/:id/voidBearer token
- POST /api/v1/packets/:id/resendBearer token
- POST /api/v1/packets/:id/correctBearer token
POST /api/v1/packets/:id/send returns emailSent and emailError next to the signing URL. Send an Idempotency-Key on create, fill, and send when a retry must not open a second packet.
Webhooks
Inkpacket posts envelope events to the workspace webhook URL. Each delivery sets X-Inkpacket-Signature to t=<unix seconds>,v1=<hex>. v1 is HMAC-SHA256 of ${timestamp}.${rawBody}, using the workspace webhook secret as the key. Compare that header to a signature you compute over the raw body before you trust the JSON.
Failed deliveries retry up to 5 times. The hourly job sends the retries. A test event is available from Settings after the webhook URL is saved.