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.json

Reference

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

  • 200 The key
  • 401 unauthorized, key_revoked or key_expired
  • 403 source_not_allowed, scope_missing or product_not_allowed
  • 429 rate_limited or daily_limit_reached
  • 503 provider_unavailable (retry later, with the same Idempotency-Key) or api_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

  • 200 The products
  • 401 unauthorized, key_revoked or key_expired
  • 403 source_not_allowed, scope_missing or product_not_allowed
  • 429 rate_limited or daily_limit_reached
  • 503 provider_unavailable (retry later, with the same Idempotency-Key) or api_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

  • 200 Already issued: for this Idempotency-Key and body, or with exactly these values through another channel
  • 201 Issued
  • 400 Malformed request: invalid_request, idempotency_key_required
  • 401 unauthorized, key_revoked or key_expired
  • 403 source_not_allowed, scope_missing or product_not_allowed
  • 409 idempotency_key_reused, request_in_progress, already_issued or product_unavailable
  • 413 Body larger than 32 KiB
  • 415 Content-Type is not application/json
  • 422 invalid_issuance: the values do not fit the product; issues names each field
  • 429 rate_limited or daily_limit_reached
  • 503 provider_unavailable (retry later, with the same Idempotency-Key) or api_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

  • 200 Valid: this is the credential the same body would issue
  • 400 Malformed request: invalid_request
  • 401 unauthorized, key_revoked or key_expired
  • 403 source_not_allowed, scope_missing or product_not_allowed
  • 409 product_unavailable
  • 413 Body larger than 32 KiB
  • 415 Content-Type is not application/json
  • 422 invalid_issuance: the values do not fit the product; issues names each field
  • 429 rate_limited or daily_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 (the offerId of the link file).

Responses

  • 200 The credential
  • 401 unauthorized, key_revoked or key_expired
  • 403 source_not_allowed, scope_missing or product_not_allowed
  • 404 not_found (also for another institution's credential) or no_verification_link
  • 429 rate_limited or daily_limit_reached
  • 503 provider_unavailable (retry later, with the same Idempotency-Key) or api_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 (the offerId of the link file).

Example request body

{
  "reason": "ISSUED_IN_ERROR"
}

Responses

  • 200 Withdrawn
  • 400 invalid_request
  • 401 unauthorized, key_revoked or key_expired
  • 403 source_not_allowed, scope_missing or product_not_allowed
  • 404 not_found (also for another institution's credential) or no_verification_link
  • 413 Body larger than 32 KiB
  • 415 Content-Type is not application/json
  • 429 rate_limited or daily_limit_reached
  • 503 provider_unavailable (retry later, with the same Idempotency-Key) or api_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 (the offerId of the link file).
  • format (query)
  • size (query) – Width in pixels

Responses

  • 200 The QR code
  • 400 invalid_request: unknown format or size
  • 401 unauthorized, key_revoked or key_expired
  • 403 source_not_allowed, scope_missing or product_not_allowed
  • 404 not_found (also for another institution's credential) or no_verification_link
  • 429 rate_limited or daily_limit_reached
  • 503 provider_unavailable (retry later, with the same Idempotency-Key) or api_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 from GET /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

  • 200 The file was read; each row is reported in results
  • 400 Malformed request: invalid_request (no or invalid product)
  • 401 unauthorized, key_revoked or key_expired
  • 403 source_not_allowed, scope_missing or product_not_allowed
  • 409 product_unavailable
  • 413 invalid_request: body larger than 256 KiB, or more than 25 rows
  • 415 unsupported_media_type: Content-Type is not text/csv
  • 422 invalid_issuance: the file does not fit the product (unreadable, no rows, unknown or missing columns); issues names each; nothing was issued
  • 429 rate_limited or daily_limit_reached
  • 503 provider_unavailable (retry later, with the same Idempotency-Key) or api_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

VersionDateChangesAction for you
1.1.217 November 2026
  • Documentation only: invented examples instead of a customer example; versioning policy and this changelog; the duplicates rule of POST /credentials worded precisely.
None
1.1.117 November 2026
  • POST /imports reports a row already issued in the SAPIO web application as 409 already_issued (was idempotency_key_reused), like POST /credentials.
None
1.1.017 November 2026
  • POST /credentials/validate: every check of an issuance, without issuing.
  • The recipient comes only from the e-mail field; an invalid address is refused (issue invalid_recipient_email).
  • POST /credentials never issues the same values twice across API channels; 409 already_issued for values issued in the web application.
  • Per-field rules (constraints) per product version, listed by GET /products; issue constraint_violated.
Optional
1.0.05 November 2026
  • First release: me, products, credentials (issue, read, withdraw, verification link and QR).
  • POST /imports (CSV), added the same day without a version change.
None