Developers · API v1 · contract 1.1.2
SAPIO Issuance API
Issue, check and withdraw verifiable credentials from your own system.
Overview
Server-to-server API for institutions issuing credentials with SAPIO. One call issues one credential composed from a credential product your institution has set up; the response carries the credential's verification URL for the QR code on your certificate, and SAPIO e-mails the recipient the wallet offer as with a file upload.
Authentication: an API key issued by SAPIO, sent as Authorization: Bearer <key>. Each key is bound to one organisation, to the products it may issue, to the scopes issue, read and withdraw, to your servers' source addresses, to a 24-hour issuance limit and to an expiry date. Never put a key in a browser, an app or a repository.
Errors are RFC 9457 problem details with a stable code; quote requestId to SAPIO support.
Versioning and changes: v1 only grows - new endpoints, new optional fields, new problem codes - so ignore what you do not know. The version of this document says what changed: patch = documentation only, minor = additive. A change that would break an integration comes as /api/v2, announced in advance, with v1 kept running in between. x-changelog lists every version, newest first, with the action it asks of you.
- Base URL
https://app.sapio.id/api/v1 - Contract (OpenAPI 3.1):
https://app.sapio.id/api/v1/openapi. Import it into Postman, Insomnia or Swagger Editor. - Access: API keys are issued by SAPIO, a test key first and a live key after a joint test. Ask at info@sapio.id.
Quick start
KEY='sapio_test_…' # from SAPIO; server to server only, never in a browser
API=https://app.sapio.id/api/v1
curl -s "$API/me" -H "Authorization: Bearer $KEY"
curl -s "$API/products" -H "Authorization: Bearer $KEY"
# Check first: nothing is signed or sent
curl -s -X POST "$API/credentials/validate" -H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" -d @body.json
# Then issue, with your own Idempotency-Key per record
curl -s -X POST "$API/credentials" -H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" -H "Idempotency-Key: record-48213-v1" -d @body.jsonReference
GET /me
The key making the request
Its limits, today's use and the source address SAPIO sees. Use it to test your setup. Scope: read.
Responses
200The key401unauthorized,key_revokedorkey_expired403source_not_allowed,scope_missingorproduct_not_allowed429rate_limitedordaily_limit_reached503provider_unavailable(retry later, with the same Idempotency-Key) orapi_unavailable
GET /products
The credential products this key may issue
With the fields each one needs in learner. A field path with a dot is a nested object: result.grade is {"result": {"grade": …}}. Scope: read.
Responses
200The products401unauthorized,key_revokedorkey_expired403source_not_allowed,scope_missingorproduct_not_allowed429rate_limitedordaily_limit_reached503provider_unavailable(retry later, with the same Idempotency-Key) orapi_unavailable
POST /credentials
Issue one credential
Composes the credential from the product's published version and the learner's values, signs it under your institution's identity, e-mails the recipient the wallet offer and returns the verification URL. Scope: issue.
Retries are safe: send the same Idempotency-Key with the same body and you receive the credential already issued (200, replayed: true), never a second one. A different body with a used key is refused (409).
The same values are never issued twice. When a credential with exactly these values (same product version, same learner fields) was already issued through the API - an earlier call with another Idempotency-Key, or a row of POST /imports - and has not been withdrawn, you receive that credential (200, replayed: true) instead of a second one. When the values were issued in the SAPIO web application (a form or a file uploaded there), the request is refused with 409 already_issued.
Parameters
Idempotency-Key(header, required) – Your own unique value for this issuance, e.g. your own record id. Reuse it for retries of the same request only.
Example request body
{
"productKey": "test-course-certificate",
"productVersion": 1,
"learner": {
"email": "alex.example@example.com",
"participantName": "Alex Example",
"courseTitle": "Data Literacy Essentials",
"completedOn": "2026-06-30",
"hours": 40,
"topics": [
"Data quality",
"Visualisation"
],
"result": {
"grade": "Pass"
}
}
}Responses
200Already issued: for this Idempotency-Key and body, or with exactly these values through another channel201Issued400Malformed request:invalid_request,idempotency_key_required401unauthorized,key_revokedorkey_expired403source_not_allowed,scope_missingorproduct_not_allowed409idempotency_key_reused,request_in_progress,already_issuedorproduct_unavailable413Body larger than 32 KiB415Content-Type is not application/json422invalid_issuance: the values do not fit the product;issuesnames each field429rate_limitedordaily_limit_reached503provider_unavailable(retry later, with the same Idempotency-Key) orapi_unavailable
POST /credentials/validate
Check one credential without issuing it
Runs every check POST /credentials makes on the same body, and nothing it does: no credential is signed, no e-mail is sent, no Idempotency-Key is needed and the call does not count against the 24-hour issuance limit. Scope: issue.
200 returns the credential exactly as it would be composed from the product version, so field mappings can be compared value by value; credentialId and the issuance date are placeholders filled in at issuance. 422 returns the same issues an issuance would. Use it to check every record, older ones included, before issuing.
Example request body
{
"productKey": "test-course-certificate",
"productVersion": 1,
"learner": {
"email": "alex.example@example.com",
"participantName": "Alex Example",
"courseTitle": "Data Literacy Essentials",
"completedOn": "2026-06-30",
"hours": 40,
"topics": [
"Data quality",
"Visualisation"
],
"result": {
"grade": "Pass"
}
}
}Responses
200Valid: this is the credential the same body would issue400Malformed request:invalid_request401unauthorized,key_revokedorkey_expired403source_not_allowed,scope_missingorproduct_not_allowed409product_unavailable413Body larger than 32 KiB415Content-Type is not application/json422invalid_issuance: the values do not fit the product;issuesnames each field429rate_limitedordaily_limit_reached
GET /credentials/{id}
Where one credential stands
The same verdict the public verification page shows. Scope: read.
Parameters
id(path, required) – The credential id returned at issuance (theofferIdof the link file).
Responses
200The credential401unauthorized,key_revokedorkey_expired403source_not_allowed,scope_missingorproduct_not_allowed404not_found(also for another institution's credential) orno_verification_link429rate_limitedordaily_limit_reached503provider_unavailable(retry later, with the same Idempotency-Key) orapi_unavailable
POST /credentials/{id}/withdraw
Withdraw one credential, permanently
The verification page shows the credential as withdrawn at once; the wallet copy is revoked too (an offer not yet accepted is revoked once accepted). A correction is: withdraw, then issue a new credential, which has a new verification URL. Repeating a withdrawal succeeds again. Scope: withdraw.
Parameters
id(path, required) – The credential id returned at issuance (theofferIdof the link file).
Example request body
{
"reason": "ISSUED_IN_ERROR"
}Responses
200Withdrawn400invalid_request401unauthorized,key_revokedorkey_expired403source_not_allowed,scope_missingorproduct_not_allowed404not_found(also for another institution's credential) orno_verification_link413Body larger than 32 KiB415Content-Type is not application/json429rate_limitedordaily_limit_reached503provider_unavailable(retry later, with the same Idempotency-Key) orapi_unavailable
GET /credentials/{id}/verification-link
The credential's verification URL again
Print it as a QR code exactly as given: it contains a #, and everything after it is needed. Scope: read.
Parameters
id(path, required) – The credential id returned at issuance (theofferIdof the link file).
Responses
200The URL401unauthorized,key_revokedorkey_expired403source_not_allowed,scope_missingorproduct_not_allowed404not_found(also for another institution's credential) orno_verification_link429rate_limitedordaily_limit_reached503provider_unavailable(retry later, with the same Idempotency-Key) orapi_unavailable
GET /credentials/{id}/verification-qr
The QR code of the verification URL, ready for a PDF
Error correction M with a four-module quiet zone. Place it at 2 × 2 cm or larger. SVG scales without loss; PNG is size pixels wide. Scope: read.
Parameters
id(path, required) – The credential id returned at issuance (theofferIdof the link file).format(query)size(query) – Width in pixels
Responses
200The QR code400invalid_request: unknown format or size401unauthorized,key_revokedorkey_expired403source_not_allowed,scope_missingorproduct_not_allowed404not_found(also for another institution's credential) orno_verification_link429rate_limitedordaily_limit_reached503provider_unavailable(retry later, with the same Idempotency-Key) orapi_unavailable
POST /imports
Issue a cohort from a CSV file (up to 25 rows)
The CSV upload of the SAPIO dashboard as one call. The file is read exactly as the dashboard reads it: comma-separated, RFC 4180 quoting, one header per field path of GET /products (e.g. result.grade), lists separated by ;, UTF-8. A file that uploads in the dashboard imports here unchanged (CSV contract v2.1).
The file is checked as a whole first: an unknown or missing column, an unreadable file, more than 25 rows or not enough of the 24-hour limit left refuse the import and issue nothing. Then every row is issued like POST /credentials, and the response reports each row. One row failing does not stop the others.
Send a fresh file with the new recipients each time, not a growing master file. No Idempotency-Key header is needed: SAPIO recognises each row by its values (product, version and every field). A row already issued, through the API or in the SAPIO web application, is never issued again: through the API it comes back with replayed: true; when it was issued in the web application it is reported as 409 already_issued. After a timeout, send the same file again.
Parameters
product(query, required) – The product key fromGET /products.
Example request body
email,participantName,courseTitle,completedOn,hours,topics,result.grade
alex.example@example.com,Alex Example,Data Literacy Essentials,2026-06-30,40,Data quality;Visualisation,Pass
Responses
200The file was read; each row is reported inresults400Malformed request:invalid_request(no or invalidproduct)401unauthorized,key_revokedorkey_expired403source_not_allowed,scope_missingorproduct_not_allowed409product_unavailable413invalid_request: body larger than 256 KiB, or more than 25 rows415unsupported_media_type: Content-Type is not text/csv422invalid_issuance: the file does not fit the product (unreadable, no rows, unknown or missing columns);issuesnames each; nothing was issued429rate_limitedordaily_limit_reached503provider_unavailable(retry later, with the same Idempotency-Key) orapi_unavailable
Errors
Every error is application/problem+json (RFC 9457) with one of these stable codes. Quote its requestId to SAPIO support.
unauthorizedkey_revokedkey_expiredsource_not_allowedscope_missingproduct_not_allowednot_foundmethod_not_allowedunsupported_media_typeinvalid_requestidempotency_key_requiredidempotency_key_reusedrequest_in_progressalready_issuedinvalid_issuanceproduct_unavailableno_verification_linkrate_limiteddaily_limit_reachedprovider_unavailableapi_unavailableinternal_error
Changelog
| Version | Date | Changes | Action for you |
|---|---|---|---|
1.1.2 | 17 November 2026 |
| None |
1.1.1 | 17 November 2026 |
| None |
1.1.0 | 17 November 2026 |
| Optional |
1.0.0 | 5 November 2026 |
| None |