{"openapi":"3.0.1","info":{"contact":{"email":"support@binarybridges.co","name":"Binary Bridges"},"description":"The endpoints a customer organisation can call directly, plus the public signing\nand verification endpoints a signer's browser uses.\n\nOrganisation-scoped operations authenticate with an OAuth2 client-credentials\ntoken carrying the `org_api` role. Credentials are issued self-service from the\nsettings panel; the token's `bb_sign_org_id` claim scopes every request, and\nthere is no request shape that names a different organisation.\n\nThe signing ceremony and verification endpoints are deliberately unauthenticated\n— a signer is a member of the public holding a link — and are marked with an\nempty `security` array.","title":"BB-Sign API","version":"2026-08-09"},"servers":[{"url":"https://sign-api.binarybridges.co","description":"Generated server url"}],"security":[{"clientCredentials":[]}],"paths":{"/api/v1/documents":{"post":{"description":"Multipart. Uploads to organisation storage without attaching to an envelope; counts against the organisation's storage quota.","operationId":"uploadDocument","parameters":[{"in":"query","name":"orgId","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}},"required":["file"]}}}},"responses":{"201":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/UploadedDocumentResponse"}}},"description":"Created"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The request was malformed or failed validation."},"401":{"description":"No credentials, or a token this organisation's credentials cannot present. Produced by the security filter chain, so there is no response body."},"403":{"description":"Authenticated, but the token lacks the role this operation requires. No response body."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The resource is not in a state that allows this — for example sending an envelope that is already sent."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"A domain rule rejected the request."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"An organisation quota is exhausted."}},"summary":"Upload a document","tags":["document-controller"]}},"/api/v1/envelopes":{"get":{"description":"Paginated, newest first, scoped to the calling organisation by the token's `bb_sign_org_id` claim. There is no request shape that names a different organisation. Only envelopes in workspaces the caller can read are listed; `workspaceId` narrows to one of them (an unreadable one yields an empty page). `totalElements` is capped at 10,000, with `totalCapped` set when the real count is larger.","operationId":"listEnvelopes","parameters":[{"in":"query","name":"page","required":false,"schema":{"type":"integer","format":"int32","default":0}},{"in":"query","name":"size","required":false,"schema":{"type":"integer","format":"int32","default":20}},{"in":"query","name":"status","required":false,"schema":{"type":"string"}},{"in":"query","name":"labels","required":false,"schema":{"type":"string"}},{"in":"query","name":"fromDate","required":false,"schema":{"type":"string","format":"date-time"}},{"in":"query","name":"toDate","required":false,"schema":{"type":"string","format":"date-time"}},{"in":"query","name":"title","required":false,"schema":{"type":"string"}},{"in":"query","name":"workspaceId","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/PagedEnvelopeResponse"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The request was malformed or failed validation."},"401":{"description":"No credentials, or a token this organisation's credentials cannot present. Produced by the security filter chain, so there is no response body."},"403":{"description":"Authenticated, but the token lacks the role this operation requires. No response body."}},"summary":"List envelopes","tags":["envelope-controller"]},"post":{"description":"Creates a draft envelope with its signers. An envelope cannot be created without at least one signer. The envelope is not sent until `sendEnvelope`. It is filed in `workspaceId` (see `listWorkspaces`), or in the organisation's General workspace when omitted; the caller needs `envelope:create` there, and a workspace it cannot create in answers 404 `WORKSPACE_NOT_FOUND`.","operationId":"createEnvelope","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEnvelopeRequest"}}},"required":true},"responses":{"201":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/EnvelopeResponse"}}},"description":"Created"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The request was malformed or failed validation."},"401":{"description":"No credentials, or a token this organisation's credentials cannot present. Produced by the security filter chain, so there is no response body."},"403":{"description":"Authenticated, but the token lacks the role this operation requires. No response body."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The resource is not in a state that allows this — for example sending an envelope that is already sent."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"A domain rule rejected the request."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"An organisation quota is exhausted."}},"summary":"Create an envelope","tags":["envelope-controller"]}},"/api/v1/envelopes/stats":{"get":{"description":"Counts for the calling organisation, for a dashboard tile, over the workspaces the caller can read (`workspaceId` narrows to one). Cheap: one grouped count, not a list.","operationId":"getEnvelopeStats","parameters":[{"in":"query","name":"workspaceId","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/EnvelopeStatsResponse"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The request was malformed or failed validation."},"401":{"description":"No credentials, or a token this organisation's credentials cannot present. Produced by the security filter chain, so there is no response body."},"403":{"description":"Authenticated, but the token lacks the role this operation requires. No response body."}},"summary":"Envelope counts by status","tags":["envelope-controller"]}},"/api/v1/envelopes/{id}":{"get":{"description":"Returns the envelope with its signers and their current statuses.","operationId":"getEnvelope","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/EnvelopeResponse"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The request was malformed or failed validation."},"401":{"description":"No credentials, or a token this organisation's credentials cannot present. Produced by the security filter chain, so there is no response body."},"403":{"description":"Authenticated, but the token lacks the role this operation requires. No response body."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"No such resource, or it belongs to another organisation. Deliberately not a 403: a 403 across a tenant boundary confirms the id exists."}},"summary":"Fetch one envelope","tags":["envelope-controller"]}},"/api/v1/envelopes/{id}/cancel":{"post":{"description":"Invalidates every outstanding signing link and fires `envelope.cancelled`. Cannot be undone; a cancelled envelope cannot be re-sent.","operationId":"cancelEnvelope","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"No Content"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The request was malformed or failed validation."},"401":{"description":"No credentials, or a token this organisation's credentials cannot present. Produced by the security filter chain, so there is no response body."},"403":{"description":"Authenticated, but the token lacks the role this operation requires. No response body."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"No such resource, or it belongs to another organisation. Deliberately not a 403: a 403 across a tenant boundary confirms the id exists."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The resource is not in a state that allows this — for example sending an envelope that is already sent."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"A domain rule rejected the request."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"An organisation quota is exhausted."}},"summary":"Cancel a sent envelope","tags":["envelope-controller"]}},"/api/v1/envelopes/{id}/documents":{"get":{"description":"Includes short-lived download URLs. Treat the URLs as secrets: they grant access to the document without a token. URLs are null unless the caller holds `document:download` in the envelope's workspace.","operationId":"listEnvelopeDocuments","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DocumentWithUrlsResponse"}}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The request was malformed or failed validation."},"401":{"description":"No credentials, or a token this organisation's credentials cannot present. Produced by the security filter chain, so there is no response body."},"403":{"description":"Authenticated, but the token lacks the role this operation requires. No response body."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"No such resource, or it belongs to another organisation. Deliberately not a 403: a 403 across a tenant boundary confirms the id exists."}},"summary":"List an envelope's documents","tags":["envelope-controller"]},"post":{"description":"Multipart. Only valid while the envelope is a draft — documents cannot change after it is sent, or the signature would not cover what the signer saw.","operationId":"uploadEnvelopeDocument","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}},"required":["file"]}}}},"responses":{"201":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/DocumentResponse"}}},"description":"Created"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The request was malformed or failed validation."},"401":{"description":"No credentials, or a token this organisation's credentials cannot present. Produced by the security filter chain, so there is no response body."},"403":{"description":"Authenticated, but the token lacks the role this operation requires. No response body."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"No such resource, or it belongs to another organisation. Deliberately not a 403: a 403 across a tenant boundary confirms the id exists."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The resource is not in a state that allows this — for example sending an envelope that is already sent."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"A domain rule rejected the request."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"An organisation quota is exhausted."}},"summary":"Attach a document to an envelope","tags":["envelope-controller"]}},"/api/v1/envelopes/{id}/send":{"post":{"description":"Transitions the envelope to SENT, emails each signer their link, and returns the signing tokens. **This is the point of no return**: documents and signers are frozen, and the `envelope.sent` webhook fires.","operationId":"sendEnvelope","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/SendResponse"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The request was malformed or failed validation."},"401":{"description":"No credentials, or a token this organisation's credentials cannot present. Produced by the security filter chain, so there is no response body."},"403":{"description":"Authenticated, but the token lacks the role this operation requires. No response body."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"No such resource, or it belongs to another organisation. Deliberately not a 403: a 403 across a tenant boundary confirms the id exists."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The resource is not in a state that allows this — for example sending an envelope that is already sent."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"A domain rule rejected the request."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"An organisation quota is exhausted."}},"summary":"Send an envelope for signature","tags":["envelope-controller"]}},"/api/v1/envelopes/{id}/signers":{"post":{"description":"Only valid while the envelope is a draft.","operationId":"addSigner","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddSignerRequest"}}},"required":true},"responses":{"201":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/SignerResponse"}}},"description":"Created"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The request was malformed or failed validation."},"401":{"description":"No credentials, or a token this organisation's credentials cannot present. Produced by the security filter chain, so there is no response body."},"403":{"description":"Authenticated, but the token lacks the role this operation requires. No response body."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"No such resource, or it belongs to another organisation. Deliberately not a 403: a 403 across a tenant boundary confirms the id exists."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The resource is not in a state that allows this — for example sending an envelope that is already sent."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"A domain rule rejected the request."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"An organisation quota is exhausted."}},"summary":"Add a signer to a draft envelope","tags":["envelope-controller"]}},"/api/v1/sign/{token}":{"get":{"description":"The signer's entry point. Returns the envelope, its documents and whether an OTP is required. Unauthenticated — the token in the path IS the credential.","operationId":"getSigningAccess","parameters":[{"in":"path","name":"token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/SigningAccessResponse"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The request was malformed or failed validation."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"No such resource, or it belongs to another organisation. Deliberately not a 403: a 403 across a tenant boundary confirms the id exists."}},"security":[],"summary":"Open a signing link","tags":["signing-controller"]}},"/api/v1/sign/{token}/request-otp":{"post":{"description":"Only for envelopes configured with `otpRequired`. Inside the resend cooldown this returns the challenge already delivered rather than issuing a new one, so a signer who reloads keeps the code they were sent.","operationId":"requestSigningOtp","parameters":[{"in":"path","name":"token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/OtpRequestResponse"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The request was malformed or failed validation."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"No such resource, or it belongs to another organisation. Deliberately not a 403: a 403 across a tenant boundary confirms the id exists."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The resource is not in a state that allows this — for example sending an envelope that is already sent."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"A domain rule rejected the request."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"An organisation quota is exhausted."}},"security":[],"summary":"Request a one-time code","tags":["signing-controller"]}},"/api/v1/sign/{token}/sign":{"post":{"description":"Applies the signature and fires `signer.signed`. When the last signer signs, the envelope completes and `envelope.completed` fires.","operationId":"submitSignature","parameters":[{"in":"path","name":"token","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignRequest"}}},"required":true},"responses":{"200":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/SignResponse"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The request was malformed or failed validation."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"No such resource, or it belongs to another organisation. Deliberately not a 403: a 403 across a tenant boundary confirms the id exists."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The resource is not in a state that allows this — for example sending an envelope that is already sent."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"A domain rule rejected the request."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"An organisation quota is exhausted."}},"security":[],"summary":"Sign the documents","tags":["signing-controller"]}},"/api/v1/sign/{token}/signed-documents":{"get":{"description":"The signer's own copy of the completed documents. Requires that this link was used to sign and that the envelope is complete — the inverse of the signing gates. Returns `signedDocumentsReady=false` while the signed PDF is still being generated. Unauthenticated — the token in the path IS the credential.","operationId":"getSignedCopy","parameters":[{"in":"path","name":"token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/SignedCopyResponse"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The request was malformed or failed validation."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"No such resource, or it belongs to another organisation. Deliberately not a 403: a 403 across a tenant boundary confirms the id exists."}},"security":[],"summary":"Download your signed copy","tags":["signing-controller"]}},"/api/v1/sign/{token}/verify-otp":{"post":{"description":"Exchanges the code for permission to sign. Fires `signer.viewed` on first successful access.","operationId":"verifySigningOtp","parameters":[{"in":"path","name":"token","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyOtpRequest"}}},"required":true},"responses":{"200":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/VerifyOtpResponse"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The request was malformed or failed validation."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"No such resource, or it belongs to another organisation. Deliberately not a 403: a 403 across a tenant boundary confirms the id exists."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The resource is not in a state that allows this — for example sending an envelope that is already sent."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"A domain rule rejected the request."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"An organisation quota is exhausted."}},"security":[],"summary":"Verify a one-time code","tags":["signing-controller"]}},"/api/v1/sign/{token}/view-closed":{"post":{"description":"Completes the open/close pair in the audit trail.","operationId":"recordDocumentClosed","parameters":[{"in":"path","name":"token","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ViewClosedRequest"}}}},"responses":{"204":{"description":"No Content"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The request was malformed or failed validation."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"No such resource, or it belongs to another organisation. Deliberately not a 403: a 403 across a tenant boundary confirms the id exists."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The resource is not in a state that allows this — for example sending an envelope that is already sent."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"A domain rule rejected the request."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"An organisation quota is exhausted."}},"security":[],"summary":"Record that a document was closed","tags":["signing-controller"]}},"/api/v1/sign/{token}/view-opened":{"post":{"description":"Telemetry for the audit trail — a signer must open each document before signing is enabled. Idempotent within a short dedup window.","operationId":"recordDocumentOpened","parameters":[{"in":"path","name":"token","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No Content"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The request was malformed or failed validation."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"No such resource, or it belongs to another organisation. Deliberately not a 403: a 403 across a tenant boundary confirms the id exists."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The resource is not in a state that allows this — for example sending an envelope that is already sent."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"A domain rule rejected the request."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"An organisation quota is exhausted."}},"security":[],"summary":"Record that a document was opened","tags":["signing-controller"]}},"/api/v1/verify":{"get":{"description":"Public. Checks a signed PDF's CMS/PKCS#7 signature and returns who signed it and when. Requires no credentials — a verifiable artefact that needed a token to verify would not be verifiable.","operationId":"verifyDocument","parameters":[{"in":"query","name":"id","required":true,"schema":{"type":"string","format":"uuid"}},{"in":"query","name":"h","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/VerifyResponse"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The request was malformed or failed validation."}},"security":[],"summary":"Verify a signed document","tags":["verify-controller"]}},"/api/v1/workspaces":{"get":{"description":"Admins: every workspace in the organisation. Members and API keys: General plus the workspaces they hold a role in. Pass an `id` as `workspaceId` when creating an envelope.","operationId":"listWorkspaces","responses":{"200":{"content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WorkspaceSummary"}}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The request was malformed or failed validation."},"401":{"description":"No credentials, or a token this organisation's credentials cannot present. Produced by the security filter chain, so there is no response body."},"403":{"description":"Authenticated, but the token lacks the role this operation requires. No response body."}},"summary":"List the workspaces you can reach","tags":["workspace-controller"]}}},"components":{"schemas":{"AddSignerRequest":{"required":["email","name"],"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string"},"signOrder":{"type":"integer","format":"int32"}}},"CreateEnvelopeRequest":{"required":["title"],"type":"object","properties":{"documentIds":{"type":"array","items":{"type":"string","format":"uuid"}},"expiresAt":{"type":"string","format":"date-time"},"labels":{"type":"object","additionalProperties":{"type":"string"}},"linkTtlHours":{"type":"integer","format":"int32"},"message":{"type":"string"},"orgId":{"type":"string","format":"uuid"},"otpRequired":{"type":"boolean"},"sequentialSigning":{"type":"boolean"},"signers":{"type":"array","items":{"$ref":"#/components/schemas/CreateSignerSpec"}},"title":{"type":"string"},"workspaceId":{"type":"string","format":"uuid"}}},"CreateSignerSpec":{"required":["email","name"],"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string"},"signOrder":{"type":"integer","format":"int32"}}},"DocumentInfo":{"required":["downloadUrl","filename","id"],"type":"object","properties":{"downloadUrl":{"type":"string"},"filename":{"type":"string"},"id":{"type":"string","format":"uuid"}}},"DocumentResponse":{"required":["contentType","filename","id"],"type":"object","properties":{"contentType":{"type":"string"},"filename":{"type":"string"},"id":{"type":"string","format":"uuid"}}},"DocumentWithUrlsResponse":{"required":["filename","id"],"type":"object","properties":{"downloadUrl":{"type":"string"},"filename":{"type":"string"},"id":{"type":"string","format":"uuid"},"signedUrl":{"type":"string"}}},"EnvelopeResponse":{"required":["archived","createdAt","documentCount","id","labels","orgId","otpRequired","sequentialSigning","signers","status","title"],"type":"object","properties":{"archived":{"type":"boolean"},"archivedAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string"},"documentCount":{"type":"integer","format":"int32"},"expiresAt":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"labels":{"type":"object","additionalProperties":{"type":"string"}},"message":{"type":"string"},"orgId":{"type":"string","format":"uuid"},"otpRequired":{"type":"boolean"},"sequentialSigning":{"type":"boolean"},"signers":{"type":"array","items":{"$ref":"#/components/schemas/SignerResponse"}},"status":{"type":"string"},"title":{"type":"string"},"workspaceId":{"type":"string","format":"uuid"},"workspaceName":{"type":"string"}}},"EnvelopeStatsResponse":{"required":["cancelled","completed","draft","expired","inProgress","sent","total"],"type":"object","properties":{"cancelled":{"type":"integer","format":"int64"},"completed":{"type":"integer","format":"int64"},"draft":{"type":"integer","format":"int64"},"expired":{"type":"integer","format":"int64"},"inProgress":{"type":"integer","format":"int64"},"sent":{"type":"integer","format":"int64"},"total":{"type":"integer","format":"int64"}}},"ErrorResponse":{"required":["code","error","message","path","status","timestamp"],"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"},"quota":{"$ref":"#/components/schemas/QuotaViolation"},"status":{"type":"integer","format":"int32"},"timestamp":{"type":"string","format":"date-time"},"traceId":{"type":"string"}}},"OtpRequestResponse":{"required":["codeUnusable","expiresInSeconds","message","resendAvailableInSeconds","resent"],"type":"object","properties":{"challengeId":{"type":"string","format":"uuid","nullable":true},"codeUnusable":{"type":"boolean"},"expiresInSeconds":{"type":"integer","format":"int64"},"message":{"type":"string"},"resendAvailableInSeconds":{"type":"integer","format":"int64"},"resent":{"type":"boolean"}}},"PagedEnvelopeResponse":{"required":["content","page","size","totalCapped","totalElements","totalPages"],"type":"object","properties":{"content":{"type":"array","items":{"$ref":"#/components/schemas/EnvelopeResponse"}},"page":{"type":"integer","format":"int32"},"size":{"type":"integer","format":"int32"},"totalCapped":{"type":"boolean"},"totalElements":{"type":"integer","format":"int64"},"totalPages":{"type":"integer","format":"int32"}}},"QuotaViolation":{"required":["current","dimension","limit"],"type":"object","properties":{"current":{"type":"integer","format":"int64"},"dimension":{"type":"string"},"limit":{"type":"integer","format":"int64"}}},"SendResponse":{"required":["envelopeId","signerTokens"],"type":"object","properties":{"envelopeId":{"type":"string","format":"uuid"},"signerTokens":{"type":"object","additionalProperties":{"type":"string"}}}},"SignRequest":{"required":["signatureImage"],"type":"object","properties":{"challengeId":{"type":"string","format":"uuid"},"otpCode":{"type":"string"},"signatureImage":{"type":"string"}}},"SignResponse":{"required":["completed","envelopeId","message","signedDocumentUrls"],"type":"object","properties":{"completed":{"type":"boolean"},"envelopeId":{"type":"string","format":"uuid"},"message":{"type":"string"},"signedDocumentUrls":{"type":"object","additionalProperties":{"type":"string"}}}},"SignedCopyResponse":{"required":["archived","documents","envelopeId","envelopeTitle","signedDocumentsReady","signerName"],"type":"object","properties":{"archived":{"type":"boolean"},"documents":{"type":"array","items":{"$ref":"#/components/schemas/SignedDocumentInfo"}},"envelopeId":{"type":"string","format":"uuid"},"envelopeTitle":{"type":"string"},"signedDocumentsReady":{"type":"boolean"},"signerName":{"type":"string"}}},"SignedDocumentInfo":{"required":["filename","id","signedDownloadUrl"],"type":"object","properties":{"filename":{"type":"string"},"id":{"type":"string","format":"uuid"},"signedDownloadUrl":{"type":"string"}}},"SignerResponse":{"required":["email","id","name","signOrder","status"],"type":"object","properties":{"email":{"type":"string"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"signOrder":{"type":"integer","format":"int32"},"signedAt":{"type":"string","format":"date-time"},"status":{"type":"string"}}},"SigningAccessResponse":{"required":["alreadySigned","documents","envelopeId","envelopeTitle","requiresOtp","signerEmail","signerName"],"type":"object","properties":{"alreadySigned":{"type":"boolean"},"documents":{"type":"array","items":{"$ref":"#/components/schemas/DocumentInfo"}},"envelopeId":{"type":"string","format":"uuid"},"envelopeTitle":{"type":"string"},"requiresOtp":{"type":"boolean"},"signerEmail":{"type":"string"},"signerName":{"type":"string"}}},"UploadedDocumentResponse":{"required":["contentType","createdAt","filename","id"],"type":"object","properties":{"contentType":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"filename":{"type":"string"},"id":{"type":"string","format":"uuid"},"sizeBytes":{"type":"integer","format":"int64"}}},"VerifyOtpRequest":{"required":["challengeId","code"],"type":"object","properties":{"challengeId":{"type":"string","format":"uuid"},"code":{"type":"string"}}},"VerifyOtpResponse":{"required":["message","verified"],"type":"object","properties":{"message":{"type":"string"},"verified":{"type":"boolean"}}},"VerifyResponse":{"required":["message","valid"],"type":"object","properties":{"envelopeId":{"type":"string","format":"uuid"},"message":{"type":"string"},"signedAt":{"type":"string","format":"date-time"},"signerEmail":{"type":"string"},"signerName":{"type":"string"},"valid":{"type":"boolean"}}},"ViewClosedRequest":{"type":"object","properties":{"durationMs":{"type":"integer","format":"int64"}}},"WebhookEvent":{"required":["apiVersion","createdAt","data","id","type"],"type":"object","properties":{"apiVersion":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/WebhookEventData"},"id":{"type":"string","format":"uuid"},"type":{"type":"string","description":"One of exactly six values. Asserted against DispatchableEvent.PUBLIC_NAMES.","enum":["envelope.sent","envelope.completed","envelope.cancelled","envelope.expired","signer.signed","signer.viewed"]}},"description":"The body of a webhook delivery. Signed per RFC-style HMAC; see docs/api/webhook-signature-spec.md."},"WebhookEventData":{"required":["envelope"],"type":"object","properties":{"envelope":{"$ref":"#/components/schemas/WebhookEventEnvelope"},"signer":{"$ref":"#/components/schemas/WebhookEventSigner"}},"description":"Per-type payload. `envelope` is always present; `signer` only for signer.* events."},"WebhookEventEnvelope":{"required":["createdAt","id","status","title"],"type":"object","properties":{"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"title":{"type":"string"}}},"WebhookEventSigner":{"required":["email","id","name","signOrder","status"],"type":"object","properties":{"email":{"type":"string"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"signOrder":{"type":"integer","format":"int32"},"signedAt":{"type":"string","format":"date-time"},"status":{"type":"string"}}},"WorkspaceSummary":{"required":["createdAt","groupsReady","id","isGeneral","name","orgId"],"type":"object","properties":{"createdAt":{"type":"string","format":"date-time"},"groupsReady":{"type":"boolean"},"id":{"type":"string","format":"uuid"},"isGeneral":{"type":"boolean"},"name":{"type":"string"},"orgId":{"type":"string","format":"uuid"}}}},"securitySchemes":{"clientCredentials":{"description":"Client-credentials grant. The `bb_sign_org_id` claim is projected onto the token by an `oidc-usermodel-attribute-mapper` on the service-account user, so a machine identity is scoped exactly as a human one is.","flows":{"clientCredentials":{"scopes":{},"tokenUrl":"http://localhost:8180/realms/bbsign/protocol/openid-connect/token"}},"type":"oauth2"}}}}