Integration manual
Authentication & API access
Use scoped API keys or exchange an approved OIDC workload identity for a short-lived access token.
Choose how your server authenticates
Create credentials in Platform → API credentials. Every credential belongs to one organisation, environment and region. API keys suit server integrations; workload identity lets an approved OIDC provider authenticate a job or service without a stored MimeProtect key. Keep credentials off browsers and mobile clients.
Create a named, scoped key
Choose a recognisable name, permissions and an expiry between 1 and 90 days. Copy the key immediately: it is shown once and stored as a hash. The list shows its prefix, expiry and last use. Rotate to replace a key immediately; revocation takes effect on subsequent requests. Deploy the replacement before revoking a separately created old key when you need an overlap.
Approve your OIDC issuer
Ask us to approve your provider’s exact HTTPS issuer and public JWKS endpoint. Any approved standards-based OIDC issuer can be used. Then create a workload identity in your regional workspace with an exact subject, audience and permissions. Additional string claims can restrict the repository, project or service account. Wildcard subjects are not accepted. Copy the generated trust ID and audience into your provider configuration.
Exchange an assertion
Ask your provider for an RS256 or ES256 JWT with the configured audience and exact subject. Its header must include a key ID. Assertions must include issuer, audience, subject, issued-at and expiry, and be no more than ten minutes old. Exchange each assertion once; obtain a fresh assertion for another exchange. The returned bearer token expires within five minutes and cannot outlive the assertion.
curl https://eu.mimeprotect.com/api/security/token \
--data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
--data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:jwt" \
--data-urlencode "trust_id=$MIMEPROTECT_TRUST_ID" \
--data-urlencode "subject_token=$OIDC_ASSERTION"Use only the permissions you need
Send Authorization: Bearer followed by your key or exchanged access token. usage:read reads allowances; documents:issue issues PDFs; documents:verify checks copies; files:read downloads issued files; esignature:create creates signing requests; esignature:read reads requests, source PDFs, completed documents and evidence. calls:create, calls:read and calls:confirm control call sessions. Email permissions begin with email:. A token exchange can narrow its scope, never expand it. Disabling a trust or its issuer also blocks previously issued access tokens.
Handle limits and errors
Sandbox limits are 120 requests per minute per organisation and 60 per credential, with 20 writes per minute per organisation. Production limits are 1,200 per organisation and 600 per credential, with 120 writes. Token exchanges also have a 30-per-minute organisation ceiling. All applicable limits apply together. HTTP 429 includes Retry-After; wait before retrying, add jitter and avoid replaying a write unless you know it did not succeed. Read RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset for the burst window. X-Request-Id identifies a request for support. A 401 means authentication failed, 403 means insufficient permission, and 421 means the endpoint region does not match.
Ready to connect it?
Open your regional workspace, create a sandbox key and test the complete flow with synthetic data. Keep the returned identifiers and inspect every result before moving to production.
Open the sandbox →Discuss your requirements →