{"openapi":"3.1.0","info":{"title":"MimeProtect Digital Security API","version":"1.0.0","description":"Organisation-scoped signing and verification. Use an environment- and region-scoped API key from your dashboard. Sandbox proofs never establish production trust."},"servers":[{"url":"https://eu.mimeprotect.com","description":"European Union storage"},{"url":"https://us.mimeprotect.com","description":"United States storage"},{"url":"https://fedramp.mimeprotect.com","description":"FedRAMP storage jurisdiction"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","description":"mp_sandbox_REGION_… or mp_live_REGION_…; server-side use only; named keys expire in 1–90 days; exchanged workload tokens expire within 5 minutes"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}}},"ProofResult":{"type":"object","required":["status","title","detail"],"properties":{"status":{"type":"string","enum":["verified","mismatch","unknown","invalid","expired","error","limited"]},"title":{"type":"string"},"detail":{"type":"string"},"issuer":{"type":"string"},"mode":{"type":"string","enum":["sandbox","live"]},"scope":{"type":"string"}}}}},"paths":{"/api/security/token":{"post":{"summary":"Exchange an OIDC workload assertion","operationId":"exchangeWorkloadToken","security":[],"description":"Exchange one assertion from an approved OIDC issuer. Exact issuer, audience, subject and optional claims must match the trust. Each assertion is accepted once. Returned access tokens expire within five minutes. See the authentication guide for provider setup and permissions.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["grant_type","subject_token_type","subject_token","trust_id"],"properties":{"grant_type":{"type":"string","enum":["urn:ietf:params:oauth:grant-type:token-exchange"]},"subject_token_type":{"type":"string","enum":["urn:ietf:params:oauth:token-type:jwt"]},"subject_token":{"type":"string","description":"Fresh provider JWT; never log or expose this assertion."},"trust_id":{"type":"string","format":"uuid"},"scope":{"type":"string","description":"Optional space-separated subset of the trust permissions."}}}}}},"responses":{"200":{"description":"access_token, token_type, expires_in, issued_token_type and granted scope; never cache"},"400":{"description":"Invalid assertion, replay, target or requested scope"},"421":{"description":"Use the trust's regional endpoint"},"429":{"description":"Rate limit reached; observe Retry-After"}}}},"/api/security/usage":{"get":{"summary":"Read product allowances","operationId":"getUsage","responses":{"200":{"description":"Environment, region and current entitlement grants"},"401":{"description":"Missing or invalid API key"}}}},"/api/security/documents":{"post":{"summary":"Issue a verifiable PDF","operationId":"issueDocument","description":"Requires document allowance. Adds a proof QR footer to each page and retains an exact-file signed record for 30 days. Production requires approved issuer identity. Input PDF must have at most 5 pages and 10 MB. Print/scan text comparison is a different verification scope.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["document"],"properties":{"document":{"type":"string","format":"binary"}}}}}},"responses":{"201":{"description":"Document id, private downloadUrl, public verifyUrl, environment and expiry"},"402":{"description":"Allowance exhausted"},"403":{"description":"Issuer approval required"},"415":{"description":"Unsupported input type"}}}},"/api/security/verify-document":{"post":{"summary":"Check a document proof","operationId":"verifyDocument","description":"Recipient checks can be made through the hosted verifier without an account. Server integrations use an API key. Exact-file results distinguish changed, unsigned, expired and unauthenticated records. Uploaded files are not retained by this endpoint.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["document"],"properties":{"document":{"type":"string","format":"binary"},"proof":{"type":"string","description":"Proof id from the QR link, if known"},"mode":{"type":"string","enum":["sandbox","live"]}}}}}},"responses":{"200":{"description":"Verification outcome; inspect status and scope, not HTTP status alone","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProofResult"}}}},"413":{"description":"Upload exceeds limit"},"429":{"description":"Rate limited"}}}},"/api/security/files/{id}":{"get":{"summary":"Download your issued PDF","operationId":"downloadDocument","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"PDF, scoped to your organisation and environment","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Not owned, missing or retention expired"}}}},"/api/security/envelopes":{"post":{"summary":"Create a signing invitation","operationId":"createEnvelope","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":16,"maxLength":128},"description":"Use a unique random key per signing request. Retry unchanged document bytes and signing details with the same key for up to 24 hours to recover the same agreement and private link. Reuse with different details returns 409. Retries do not resend email; inspect delivery and deliveryMessage. Scoped to organisation, environment, region and sender (service credentials share a scope, allowing key rotation)."}],"description":"Returns a private signing link for one recipient. Deliver the link through your existing workflow or request delivery=email. Inspect delivery and deliveryMessage; failed delivery does not cancel the created envelope. Sandbox never sends email. Completion consumes one document unit. Personal free access has no business API access.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["document","title","recipient","product"],"properties":{"document":{"type":"string","format":"binary"},"title":{"type":"string","maxLength":150},"recipient":{"type":"string","format":"email"},"product":{"type":"string","enum":["esign-platform","esign-users"]},"delivery":{"type":"string","enum":["link","email"]},"fields":{"type":"string","description":"JSON array of signing fields: id, type (signature/name/date), 1-based page, x, y, width, height. Coordinates are fractions of the displayed page from its top-left. At least one signature field is required when fields are supplied."}}}}}},"responses":{"201":{"description":"Envelope id, private signing URL and 7-day invitation expiry"},"402":{"description":"Allowance required"},"403":{"description":"Business API entitlement required"},"409":{"description":"Idempotency key reused with different details, or reservation expired during processing"}}}},"/api/security/envelopes/{id}":{"get":{"summary":"Read a signing request","operationId":"getEnvelope","description":"Poll this resource to track signing. A completed request includes completedDocumentUrl and evidenceUrl. Use the same organisation, region and environment key as the request. Timestamps are Unix milliseconds.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Signing status, title, recipient, expiry and completed resource URLs"},"404":{"description":"Request missing, not accessible or expired"}}}},"/api/security/envelopes/{id}/source":{"get":{"summary":"Download the source agreement","operationId":"getEnvelopeSource","description":"Retrieve the original agreement using esignature:read permission in the matching organisation, region and environment.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Source PDF"},"404":{"description":"Request missing, not accessible or expired"}}}},"/api/security/envelopes/{id}/evidence":{"get":{"summary":"Download signing evidence","operationId":"getEnvelopeEvidence","description":"Retrieve the completion record after signing. Archive it with the completed PDF before retention expires.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Signing evidence as a JSON attachment"},"404":{"description":"Request or evidence missing, not accessible or expired"},"409":{"description":"Signing has not completed"}}}},"/api/security/call-sessions":{"post":{"summary":"Create a call or SMS verification session","operationId":"createCallSession","description":"Returns the initial one-time code. Session expires after 5 minutes. Production requires sender approval. Creation reserves capacity; only completed confirmation consumes the verification unit.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sender","purpose"],"properties":{"sender":{"type":"string","description":"E.164 phone number or 2–11 character alphanumeric SMS sender ID"},"purpose":{"type":"string","maxLength":150}}}}}},"responses":{"201":{"description":"Session id, initial code, sender, purpose, environment and expiry"},"402":{"description":"Allowance exhausted"}}}},"/api/security/call-challenge":{"post":{"summary":"Read the current agent-side return challenge","operationId":"getReturnChallenge","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id"],"properties":{"id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Code, authoritative server time, expiry, organisation and purpose; never cache"},"409":{"description":"Waiting for customer or already confirmed"},"410":{"description":"Session expired"}}}},"/api/security/call-confirm":{"post":{"summary":"Confirm a return code once","operationId":"confirmCall","description":"Current 30-second epoch only. Five failed agent attempts lock confirmation. A completed session cannot be confirmed again.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","code"],"properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string","pattern":"^[0-9]{6}$"}}}}}},"responses":{"200":{"description":"Session state confirmed; one unit consumed"},"403":{"description":"Wrong or rotated challenge"},"409":{"description":"Session already consumed"},"429":{"description":"Attempt limit reached"}}}}}}