{"openapi":"3.1.0","info":{"title":"SAPIO Issuance API","version":"1.1.2","summary":"Issue, check and withdraw verifiable credentials from your own system.","description":"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.\n\nAuthentication: 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.\n\nErrors are RFC 9457 problem details with a stable `code`; quote `requestId` to SAPIO support.\n\nVersioning 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.","contact":{"name":"SAPIO support","email":"info@sapio.id"}},"x-changelog":[{"version":"1.1.2","date":"2026-11-17","action":"none","changes":["Documentation only: invented examples instead of a customer example; versioning policy and this changelog; the duplicates rule of POST /credentials worded precisely."]},{"version":"1.1.1","date":"2026-11-17","action":"none","changes":["POST /imports reports a row already issued in the SAPIO web application as 409 already_issued (was idempotency_key_reused), like POST /credentials."]},{"version":"1.1.0","date":"2026-11-17","action":"optional","changes":["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."]},{"version":"1.0.0","date":"2026-11-05","action":"none","changes":["First release: me, products, credentials (issue, read, withdraw, verification link and QR).","POST /imports (CSV), added the same day without a version change."]}],"servers":[{"url":"https://app.sapio.id/api/v1","description":"Production (test keys issue only TEST products)"}],"security":[{"apiKey":[]}],"tags":[{"name":"Credentials"},{"name":"Account"}],"paths":{"/me":{"get":{"tags":["Account"],"operationId":"getMe","summary":"The key making the request","description":"Its limits, today's use and the source address SAPIO sees. Use it to test your setup. Scope: `read`.","responses":{"200":{"description":"The key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/products":{"get":{"tags":["Account"],"operationId":"listProducts","summary":"The credential products this key may issue","description":"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":{"description":"The products","content":{"application/json":{"schema":{"type":"object","required":["products"],"properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/credentials":{"post":{"tags":["Credentials"],"operationId":"issueCredential","summary":"Issue one credential","description":"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`.\n\nRetries 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).\n\nThe 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":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssueRequest"},"examples":{"course-certificate":{"summary":"One course certificate (invented)","value":{"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":{"description":"Already issued: for this Idempotency-Key and body, or with exactly these values through another channel","headers":{"Idempotent-Replayed":{"schema":{"type":"string","const":"true"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssueResponse"}}}},"201":{"description":"Issued","headers":{"Location":{"schema":{"type":"string"},"description":"/api/v1/credentials/{id}"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssueResponse"},"examples":{"issued":{"value":{"id":"cmw3cvc7k0001","product":{"key":"test-course-certificate","version":1},"verificationUrl":"https://app.sapio.id/verify#sqYRX6mjtgBXZnRMtrzhSCKok4VL_dJw3CFY42CnMxg","emailSent":true,"replayed":false}}}}}},"400":{"description":"Malformed request: `invalid_request`, `idempotency_key_required`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"`idempotency_key_reused`, `request_in_progress`, `already_issued` or `product_unavailable`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 32 KiB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Content-Type is not application/json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"`invalid_issuance`: the values do not fit the product; `issues` names each field","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/credentials/validate":{"post":{"tags":["Credentials"],"operationId":"validateCredential","summary":"Check one credential without issuing it","description":"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`.\n\n200 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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssueRequest"},"examples":{"course-certificate":{"summary":"One course certificate (invented)","value":{"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":{"description":"Valid: this is the credential the same body would issue","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateResponse"}}}},"400":{"description":"Malformed request: `invalid_request`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"`product_unavailable`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 32 KiB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Content-Type is not application/json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"`invalid_issuance`: the values do not fit the product; `issues` names each field","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/credentials/{id}":{"get":{"tags":["Credentials"],"operationId":"getCredential","summary":"Where one credential stands","description":"The same verdict the public verification page shows. Scope: `read`.","parameters":[{"$ref":"#/components/parameters/CredentialId"}],"responses":{"200":{"description":"The credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredentialState"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/credentials/{id}/withdraw":{"post":{"tags":["Credentials"],"operationId":"withdrawCredential","summary":"Withdraw one credential, permanently","description":"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":[{"$ref":"#/components/parameters/CredentialId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawRequest"},"examples":{"error":{"value":{"reason":"ISSUED_IN_ERROR"}},"other":{"value":{"reason":"OTHER","note":"Issued to the wrong cohort"}}}}}},"responses":{"200":{"description":"Withdrawn","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawResponse"}}}},"400":{"description":"`invalid_request`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"description":"Body larger than 32 KiB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Content-Type is not application/json","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/credentials/{id}/verification-link":{"get":{"tags":["Credentials"],"operationId":"getVerificationLink","summary":"The credential's verification URL again","description":"Print it as a QR code exactly as given: it contains a `#`, and everything after it is needed. Scope: `read`.","parameters":[{"$ref":"#/components/parameters/CredentialId"}],"responses":{"200":{"description":"The URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationLink"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/credentials/{id}/verification-qr":{"get":{"tags":["Credentials"],"operationId":"getVerificationQr","summary":"The QR code of the verification URL, ready for a PDF","description":"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":[{"$ref":"#/components/parameters/CredentialId"},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["svg","png"],"default":"svg"}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","minimum":200,"maximum":2000,"default":600},"description":"Width in pixels"}],"responses":{"200":{"description":"The QR code","content":{"image/svg+xml":{"schema":{"type":"string"}},"image/png":{"schema":{"type":"string","contentMediaType":"image/png"}}}},"400":{"description":"`invalid_request`: unknown format or size","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/imports":{"post":{"tags":["Credentials"],"operationId":"importCsv","summary":"Issue a cohort from a CSV file (up to 25 rows)","description":"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).\n\nThe 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.\n\nSend 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":[{"name":"product","in":"query","required":true,"description":"The product key from `GET /products`.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,63}$"}}],"requestBody":{"required":true,"content":{"text/csv":{"schema":{"type":"string","maxLength":262144},"example":"email,participantName,courseTitle,completedOn,hours,topics,result.grade\nalex.example@example.com,Alex Example,Data Literacy Essentials,2026-06-30,40,Data quality;Visualisation,Pass\n"}}},"responses":{"200":{"description":"The file was read; each row is reported in `results`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportResponse"}}}},"400":{"description":"Malformed request: `invalid_request` (no or invalid `product`)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"`product_unavailable`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"`invalid_request`: body larger than 256 KiB, or more than 25 rows","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"`unsupported_media_type`: Content-Type is not text/csv","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"`invalid_issuance`: the file does not fit the product (unreadable, no rows, unknown or missing columns); `issues` names each; nothing was issued","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"sapio_<test|live>_<prefix>.<secret>","description":"Issued by SAPIO, shown once. Send only from the source addresses registered for the key."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"description":"Your own unique value for this issuance, e.g. your own record id. Reuse it for retries of the same request only.","schema":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{16,200}$"},"example":"record-48213-v1"},"CredentialId":{"name":"id","in":"path","required":true,"description":"The credential id returned at issuance (the `offerId` of the link file).","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,128}$"}}},"responses":{"Unauthorized":{"description":"`unauthorized`, `key_revoked` or `key_expired`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Forbidden":{"description":"`source_not_allowed`, `scope_missing` or `product_not_allowed`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"`not_found` (also for another institution's credential) or `no_verification_link`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"TooManyRequests":{"description":"`rate_limited` or `daily_limit_reached`","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unavailable":{"description":"`provider_unavailable` (retry later, with the same Idempotency-Key) or `api_unavailable`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"schemas":{"Problem":{"type":"object","description":"RFC 9457 problem details","required":["type","title","status","code"],"properties":{"type":{"type":"string","format":"uri","example":"urn:sapio:api:v1:error:invalid_issuance"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string","enum":["unauthorized","key_revoked","key_expired","source_not_allowed","scope_missing","product_not_allowed","not_found","method_not_allowed","unsupported_media_type","invalid_request","idempotency_key_required","idempotency_key_reused","request_in_progress","already_issued","invalid_issuance","product_unavailable","no_verification_link","rate_limited","daily_limit_reached","provider_unavailable","api_unavailable","internal_error"]},"detail":{"type":"string"},"requestId":{"type":["string","null"]},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}}}},"IssueRequest":{"type":"object","additionalProperties":false,"required":["productKey","learner"],"properties":{"productKey":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,63}$","description":"From GET /products"},"productVersion":{"type":"integer","minimum":1,"description":"Omit to use the active version"},"learner":{"type":"object","description":"The values that change per person, as GET /products lists them. Nested objects or dot-path keys; lists as JSON arrays; numbers as JSON numbers with a dot; dates as YYYY-MM-DD. A blank or null value is left out. Fields the product sets itself are refused.","additionalProperties":true}}},"IssueResponse":{"type":"object","required":["id","verificationUrl","emailSent","replayed"],"properties":{"id":{"type":"string"},"product":{"type":["object","null"],"properties":{"key":{"type":"string"},"version":{"type":"integer"}}},"verificationUrl":{"type":["string","null"],"format":"uri","description":"For the QR code. Null only if the product creates no verification link."},"emailSent":{"type":["boolean","null"],"description":"Whether the wallet offer e-mail went out; null on a replay"},"replayed":{"type":"boolean"}}},"CredentialState":{"type":"object","required":["id","state","issuedOn"],"properties":{"id":{"type":"string"},"product":{"type":["object","null"],"properties":{"key":{"type":"string"},"name":{"type":"string"},"version":{"type":"integer"}}},"state":{"type":"string","enum":["valid","withdrawn","expired","undetermined"],"description":"`undetermined` when the status could not be read just now; retry later"},"wallet":{"type":["string","null"],"enum":["accepted","pending","not_accepted",null],"description":"Information only, never part of the verdict"},"issuedOn":{"type":"string","format":"date"},"validUntil":{"type":["string","null"],"format":"date"},"statusReadAt":{"type":["string","null"],"format":"date-time"}}},"WithdrawRequest":{"type":"object","additionalProperties":false,"required":["reason"],"properties":{"reason":{"type":"string","enum":["ISSUED_IN_ERROR","QUALIFICATION_WITHDRAWN","HOLDER_REQUEST","SUPERSEDED","FRAUD","OTHER"]},"note":{"type":"string","maxLength":500,"description":"Required with OTHER"}}},"WithdrawResponse":{"type":"object","required":["id","state","execution"],"properties":{"id":{"type":"string"},"state":{"type":"string","const":"withdrawn"},"execution":{"type":"string","description":"How far the wallet-side revocation got: e.g. completed, or pending for an offer not yet accepted"}}},"VerificationLink":{"type":"object","required":["id","verificationUrl"],"properties":{"id":{"type":"string"},"verificationUrl":{"type":"string","format":"uri"}}},"Product":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"activeVersion":{"type":["integer","null"]},"fields":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["string","number","boolean","array"]},"required":{"type":"boolean"},"constraints":{"type":"object","description":"Only when the product version sets any. `format: \"date\"`: a real date written YYYY-MM-DD; `notBefore`: the field this date may not precede; `min`/`max`: inclusive bounds of a number; `maxLength`: characters. A constrained text may not have leading or trailing spaces or read \"null\". A value that does not fit is refused with 422, issue `constraint_violated`.","properties":{"format":{"type":"string","enum":["date"]},"notBefore":{"type":"string"},"min":{"type":"number"},"max":{"type":"number"},"maxLength":{"type":"integer"}},"additionalProperties":false}}}}}},"Me":{"type":"object","properties":{"organizationId":{"type":"string"},"key":{"type":"object","properties":{"prefix":{"type":"string"},"label":{"type":"string"},"mode":{"type":"string","enum":["test","live"]},"scopes":{"type":"array","items":{"type":"string"}},"productKeys":{"type":"array","items":{"type":"string"}},"dailyIssueLimit":{"type":"integer"},"issuedLast24h":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"}}},"sourceIp":{"type":"string","description":"The address SAPIO sees for your request"}}},"ImportRow":{"type":"object","required":["row","status"],"properties":{"row":{"type":"integer","description":"Data row of the file, the first row after the header is 1"},"status":{"type":"integer","description":"As if the row had been sent to `POST /credentials`: 201 issued, 200 replayed, 4xx/5xx refused"},"id":{"type":"string","description":"The credential id (offerId of the link file), when issued or replayed"},"verificationUrl":{"type":["string","null"]},"emailSent":{"type":["boolean","null"]},"replayed":{"type":"boolean"},"code":{"type":"string","description":"Problem code when the row was refused"},"detail":{"type":"string"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}},"ImportResponse":{"type":"object","required":["product","rows","issued","replayed","failed","results"],"properties":{"product":{"type":"object","properties":{"key":{"type":"string"},"version":{"type":"integer"}}},"rows":{"type":"integer"},"issued":{"type":"integer"},"replayed":{"type":"integer"},"failed":{"type":"integer"},"results":{"type":"array","items":{"$ref":"#/components/schemas/ImportRow"}}}},"ValidateResponse":{"type":"object","required":["valid","product","credential"],"additionalProperties":false,"properties":{"valid":{"type":"boolean","const":true},"product":{"type":"object","required":["key","version"],"properties":{"key":{"type":"string"},"version":{"type":"integer"}}},"credential":{"type":"object","description":"The claims as they would be signed, product-managed values included.","additionalProperties":true}}}}}}