InkSeal Credentials API

openapi: 3.2.0
info:
  title: InkSeal Credentials API
  version: 1.17.0
  summary: 'Credit-based document signing: upload, place fields, send for signature, collect the signed PDF.'
  description: 'InkSeal is a credit-based document signing API. A workspace uploads a document, lays signature and data fields on it, adds signers, and sends an envelope for signature. Metered workspaces spend one credit for the envelope, one for every signer who is not the sender, and one more when the envelope requires a one-time code. Unmetered workspaces record zero-cost usage instead. This document is self-sufficient: everything below is what a client needs to drive the full attachment-to-signing workflow without reading application source. ## Authentication


    Every request carries a service credential as an HTTP bearer token:


    ```

    Authorization: Bearer isk_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

    ```


    A key is the literal prefix `isk_` followed by 40 base62 characters (44 characters in total). The server stores only a SHA-256 hash of the key plus its first 8 characters and its last 4, so a key is shown exactly once, in the response that mints it, and can never be read back. **Minting.** `POST /credentials` creates a credential and returns the raw key. A credential is bound to one workspace at creation and that binding is never changeable: no request parameter widens it, and the workspace a key reaches is fixed for the life of the key. A caller can only grant scopes it already holds, so a credential can narrow itself but never widen itself; an attempt to grant more answers 403 with code `scope_escalation`. **Rotation.** `POST /credentials/{credentialId}/rotate` mints a second secret on the same credential and returns it once. The outgoing secret keeps authenticating for a 24 hour grace window, so both keys work while a deployment rolls over; when the window closes the old secret stops authenticating. Rotating again while a predecessor is still in its grace window ends that predecessor''s window immediately. Revocation (`DELETE /credentials/{credentialId}`) has no grace period at all: it is the answer to a leak, so it takes effect on the next request. **Failure.** Every authentication failure answers `401` with code `unauthorized` and the same message: a malformed header, an unknown key, a secret past its grace window, a revoked or expired credential, and a deleted workspace are deliberately indistinguishable from outside. ## Scopes


    There are exactly eleven scopes:


    | Scope | Grants |

    | --- | --- |

    | `documents:read` | Read documents and their metadata, the normalized PDF bytes, and page images. |

    | `documents:write` | Create documents, confirm uploads, start field detection, delete documents. |

    | `envelopes:read` | Read envelopes, their signers, and their status. |

    | `envelopes:write` | Create and edit draft envelopes, void them, archive and unarchive them. |

    | `envelopes:send` | Send an envelope for signature and chase signers with reminders. Metered workspaces spend the envelope''s credits; unmetered workspaces record zero-cost usage. |

    | `templates:read` | Read reusable templates, their roles, fields, and archive state. |

    | `templates:write` | Create, replace, archive, unarchive, and delete templates. |

    | `webhooks:manage` | Create, read, edit, and delete webhook subscriptions, and inspect and retry their deliveries. |

    | `account:read` | Read the workspace''s credit balance, transactions, settings, inbox, authorized senders, and audit trail. |

    | `settings:write` | Change workspace settings, manage service credentials, and manage the addresses inbound mail is accepted from. |

    | `billing:manage` | Open a Stripe Checkout session for a credit pack. It cannot pay: a human completes the checkout. Only a workspace owner can grant this scope. |


    Each operation in this document declares its requirement under `security`. **A listed scope array is an AND, not a menu**: an operation listing `["envelopes:read", "account:read"]` requires both. A credential missing any of them gets `403` with code `insufficient_scope`, and `error.details` naming `requiredScopes` and `missingScopes` so the fix is mechanical.'
  contact:
    name: InkSeal
    url: https://inkseal.net
servers:
- url: https://inkseal.net/api/v1
  description: Production
- url: http://localhost:3000/api/v1
  description: Local development
security:
- bearerAuth: []
tags:


# --- truncated at 32 KB (47 KB total) ---
# Full source: https://artifacts.apis.io/inkseal-net/openapi/inkseal-net-credentials-api-openapi.yml