Credentials API
Credentials are the core output of the Reference Implementation. Everything else in the system — DIDs, services, data models, identifiers, and master data — exists to support one goal: issuing trusted, verifiable digital documents about products, facilities, organisations, and supply chain events.
A credential is a digitally signed statement. A company issues a credential that says "this product was made sustainably" or "this facility passed a conformity assessment". Because the credential is cryptographically signed, anyone who receives it can verify that the statement hasn't been tampered with and that it really came from the company that claims to have issued it, without needing to contact the issuer directly.
The Credentials API has three related surfaces:
- Issuance (authenticated): a tenant creates a credential, the system validates it, signs it, stores it, and optionally publishes it so it can be discovered by resolving an identifier.
- Library access (authenticated): a tenant lists and retrieves the credential records it issued or received, including custody details on record detail.
- Verification (public, no login required): anyone with a link to a stored credential can check whether it's genuine, untampered, and still valid.
The Reference Implementation includes a Swagger UI at /api-docs with full request/response schemas you can try directly from the browser. The endpoint descriptions below focus on behaviour and internal logic. Refer to Swagger for exact payload shapes. All endpoints except Verify require authentication. See Authentication for how to obtain a Bearer token.
Concepts
What's Inside a Credential?
Every credential issued by the Reference Implementation follows the W3C Verifiable Credentials Data Model and the UNTP Verifiable Credential profile. In plain terms, a credential contains:
- Who issued it — the issuer's DID (a cryptographic identity)
- What it says — the credential subject (e.g., product sustainability data, conformity assessment results)
- When it was issued — a timestamp
- A digital signature — proof that the issuer really signed it and that nobody changed it afterwards
- A credential status — a mechanism for the issuer to revoke or suspend the credential later if needed (managed via BitstringStatusList by the VC service)
How Credentials Are Packaged
UNTP credentials use the enveloped form: the credential payload is signed as a JWT (JSON Web Token), and the JWT is wrapped inside a JSON-LD envelope. This means you get the best of both worlds — compact, efficient JWT signatures with the semantic richness of linked data.
When the Reference Implementation issues a credential, the result is an EnvelopedVerifiableCredential that looks like this:
{
"@context": ["https://www.w3.org/ns/credentials/v2"],
"type": "EnvelopedVerifiableCredential",
"id": "data:application/vc+jwt,eyJhbGciOiJFZDI1NTE5..."
}
The id field contains the actual JWT. The verification endpoint knows how to unwrap this and decode the original credential payload.
Credential Types
The type of credential determines what kind of data it contains and which schema is used to validate it. Credential types are defined by data models — see the Data Models API for the full list of core UNTP types and how extension data models work.
Encryption and Privacy
When a credential is issued, two things are created: the signed credential (stored externally by the storage service) and a credential record (stored in the Reference Implementation's database, tracking metadata like the storage URI, hash, and published status).
By default, the storage service encrypts the signed credential before storing it, so the file at the storage URI is unreadable on its own. The storage service returns the decryption key once, when the credential is stored, and the Reference Implementation saves it on the credential record. Issuance returns the credential record id. An authenticated GET /api/v1/library/{id} returns the storage URI and a decryptionKey for an encrypted record when this service holds one and can reveal it, and null otherwise (see the library detail contract), so the key can be supplied during verification.
This matters for privacy: a credential about a product's supply chain might contain commercially sensitive information. Encryption ensures that only someone with the key can read it, even if they have the storage URL.
| Setting | What Happens |
|---|---|
encrypt: true (default) | Credential encrypted before storage. The library detail returns a decryptionKey when this service holds one and can reveal it, and null otherwise. |
encrypt: false | Credential stored in plaintext. Anyone with the URL can read it. |
Integrity Hashing
Every stored credential has a content hash — a fingerprint computed from the credential's contents. If even one character changes, the hash changes. This allows anyone to detect that the credential at a storage URI hasn't been swapped or modified after being stored. During verification, the computed hash is compared against the expected hash.
Discoverability via the Identity Resolver
A credential on its own is just a file at a URL. To make it useful, it needs to be discoverable — someone who knows a product's identifier should be able to find the credential. This is the role of the UNTP Identity Resolver and Decentralised Access Control specifications.
This is where the Identity Resolver comes in. When a credential is published, the Reference Implementation registers a link with the Identity Resolver that connects the entity's identifier (e.g., a GS1 GTIN) to the credential's storage URL. Now anyone who resolves that identifier can find the credential.
Publishing is optional and resolves from the credential's own identifier, which must belong to an identifier scheme reachable through an IDR service.
CVC Compliance (Conformity Credentials Only)
For UNTP v0.7.0 Digital Conformity Credentials, the issuance pipeline performs an extra advisory check: it compares the conformity scheme, profile, and criteria referenced in the credential against the locally known Conformity Vocabulary Catalogue (CVC) schemes. Earlier DCC versions are issued without this check. This helps catch mistakes like referencing a non-existent scheme or omitting a required criterion. See Conformity Vocabulary Catalogue for where those schemes come from, and the Conformity Vocabulary Catalogue API for browsing them.
CVC validation is advisory only — it never blocks issuance. If issues are found, the credential is still issued but the response includes warnings.
The Issuance Pipeline
Issuing a credential involves eight stages. Each stage can fail independently, and failures at different stages produce different HTTP status codes and warning codes. See the Issue a Credential endpoint for the full request and response reference.
Stage 1: Request Validation
The three required fields are validated:
| Field | Type | Required | Description |
|---|---|---|---|
credentialPayload | object | Yes | The full credential payload conforming to the UNTP schema for the specified type and version |
credentialType | string | Yes | Must match a registered data model (e.g., DigitalProductPassport) |
version | string | Yes | Must match a registered data model version (e.g., 0.6.1) |
Stage 2: Data Model Resolution
The credentialType and version are used to look up a registered data model. The data model provides the JSON Schema URL(s) for validation, the JSON-LD context URL, and the bridge that extracts entity references from the payload.
For extension data models, both the parent schema and the extension schema are validated.
Stage 3: Payload Validation
The credential payload is validated in two passes:
- JSON Schema validation against the data model's schema URL(s). This catches structural issues such as missing required fields, incorrect types, or invalid enum values.
- JSON-LD expansion to verify the payload is valid linked data with a resolvable
@context.
If either check fails, the request is rejected with HTTP 400, the error message says why, and a code field distinguishes the two things that can go wrong at each pass. SCHEMA_DOCUMENT_INVALID and JSONLD_DOCUMENT_INVALID mean the payload itself is invalid; the message carries the detail to fix, such as the missing property or the undefined term. SCHEMA_FETCH_FAILED and JSONLD_CONTEXT_FETCH_FAILED mean a remote schema or @context document could not be fetched or used. The schema message names the schema URL. The context message names the failing @context URL where the processor recorded one, and carries the HTTP status or timeout where one applies; the reason collapses to a general one when the URL itself was rejected, so a rejected URL cannot be used to probe what the service can reach. A document failure is fixed by correcting the payload; a fetch failure usually reflects an upstream or network condition rather than a problem with the credential. The UNTP core schemas and contexts for every release from 0.6.0 onwards, and the W3C Verifiable Credentials Data Model v2 context, ship inside the service, so an outage at their publishing host does not produce a fetch failure for those versions: the bundled copy is used and the server log records that it was, together with the fetch error. A fetch failure for one of those URLs is therefore not a host outage: it means the URL was refused by the guard, the fetch hit an unexpected error, or the schema could not be compiled. A fetch failure for any other URL means that host could not be used.
Stage 3.5: CVC Compliance Validation (Advisory)
For Digital Conformity Credentials (DCC), the issuance pipeline performs an advisory check against the locally known conformity schemes (operator-seeded in this release). This check verifies that the conformity scheme, profile, and criteria referenced in the credential payload correspond to entries in the catalogue, and that the claimed criteria line up with what the profile defines.
CVC validation is advisory only. It never blocks issuance. If the check fails or no matching scheme is available, the credential is issued with warnings in the response. Warning codes include:
| Code | Meaning |
|---|---|
conformity-scheme.not-found | A referenced conformity scheme URI is not in the locally known catalogue |
conformity-profile.not-found | A referenced profile URI is not found within the scheme |
conformity-profile.not-specified | The claim references no profile, so criterion and topic checks were not performed (criteria are published per versioned profile) |
conformity-criterion.not-in-profile | A claimed criterion is not one the referenced profile publishes |
conformity-criterion.missing | A criterion the profile defines is absent from the claim |
conformity-criterion.topic-mismatch | A criterion's declared conformity topics do not match those the criterion defines |
conformity-assessment.topic-mismatch | An assessment declares a conformity topic that none of its assessed criteria define |
conformity-claim.validation-error | Validation could not be performed (extraction or infrastructure failure) |
Criterion and topic warnings name the versioned profile URI they were checked against in their message, since profile URIs carry a version segment and the same criterion can differ between profile versions.
Alongside code and message, a warning can carry structured fields so a client can act on it without reading the message text:
| Field | What it carries |
|---|---|
received | The value that triggered the warning, such as the criterion URI the profile does not publish |
expected | The value or shape that was expected, where there is one |
pointer | A JSON pointer to the place in the credential you submitted that the warning concerns, for example /credentialSubject/conformityAssessment/0/assessmentCriteria/1/id |
remediation | What to do about it, where the check can say |
A pointer appears only where the warning has a location in your credential and that location resolves, so treat it as present-or-absent rather than guaranteed. Two warnings never carry one, because their subject is not in the document at all. conformity-criterion.missing names a criterion the claim never declared, so read expected for the criterion the profile publishes. conformity-profile.not-specified reports the absence of a profile and carries neither received nor expected, so the message is the whole of it.
The assessment-level topic check runs only when the assessment references at least one criterion and every referenced criterion resolves in the profile. An assessment that references no criteria is not warned, because its own conformityTopic is then the claim's only classification (the intended modelling when, for example, a scheme publishes no digital vocabulary of criteria); an unresolved criterion is reported as conformity-criterion.not-in-profile instead of producing a topic verdict from incomplete evidence.
Stage 4: Issuer DID Ownership Validation
The issuer.id field in the credential payload must contain a DID that the authenticated tenant is authorised to use. The Reference Implementation looks up the DID and verifies that it either:
- belongs to the authenticated tenant, or
- is a system default DID — available to all tenants as part of the incremental adoption ramp
If the DID is not registered to the tenant and is not a system default DID, the request is rejected with HTTP 400. A tenant cannot issue credentials using a DID that belongs to another tenant.
Stage 5: DID Service Association Check
The issuer DID must have an associated VC service instance — this is the service that holds the DID's key material and will perform signing. If the DID has no association (e.g., the service instance was force-deleted), the request is rejected with HTTP 400. The DID must be re-imported or re-created to restore the association.
Stage 6: Service Resolution
The VC service is resolved from the issuer DID's associated service instance. This ensures signing always happens on the VC service that holds the DID's key material, regardless of whether the DID is a tenant-owned DID or a system default DID. The caller does not need to specify which VC service to use; the DID determines it.
The storage service and IDR service follow the standard resolution chain:
| Service | Purpose | How Resolved |
|---|---|---|
| VC Service | Signs the credential payload | From the issuer DID's associated service instance |
| Storage Service | Stores the signed credential | storageOptions.serviceInstanceId, or tenant primary, or system default |
| IDR Service | Publishes links (only when publish: true) | From the resolved identifier's scheme, then its registrar, then the tenant/system default |
Stage 7: Sign, Store, and Record
The credential payload is signed by the VC service, producing an Enveloped Verifiable Credential. The signed credential is then stored by the storage service.
Encryption: By default, the stored credential is encrypted with AES-GCM. Issuance returns the credential record id, and an authenticated GET /api/v1/library/{id} returns a decryptionKey for an encrypted record when this service holds one and can reveal it, and null otherwise (see the library detail contract). Supply that key when verifying an encrypted credential. Set storageOptions.encrypt to false to store the credential unencrypted.
Entity linking: The data model bridge extracts entity references (organisations, facilities, products) from the credential payload. The primary entity (priority: product > facility > organisation) is linked to the credential record in the database. This link is best-effort enrichment; it never gates the optional publishing step, and a match that fails to link (for example the entity was deleted between extraction and insert) is reported as an advisory ENTITY_LINK_FAILED warning rather than affecting the credential or the publish.
Stage 8: IDR Publishing (Optional)
When publishingOptions.publish is true, the Reference Implementation publishes a link to the stored credential on the Identity Resolver for the credential's own identifier. This makes the credential discoverable via that identifier's scheme (e.g., resolving a GS1 GTIN leads to the credential).
The tenant's registrar and identifier scheme namespaces must already be registered with the Identity Resolver before publishing. The seed registers these namespaces only for the system tenant, so a tenant using its own registrar or scheme must register the corresponding namespaces with the resolver first.
Publishing resolves its target from the same reference used for entity linking (priority: product > facility > organisation), looked up against the tenant's identifiers rather than against master data. Publishing requires that lookup to resolve to exactly one identifier with:
- An identifier scheme that has a primary key
- A registrar with a namespace
- An IDR service instance (configured on the scheme, the registrar, or the tenant/system default)
When publishing cannot complete, the credential is still issued and returned, and a warning names the unmet prerequisite along with what to do about it:
| Code | Meaning | What to do |
|---|---|---|
REFS_EXTRACTION_FAILED | No identifier could be read from the credential payload. | Check the subject carries the identifier fields its data model defines, such as a registeredId. |
PUBLISH_REFERENCE_MISSING | The payload carries no identifier to publish under. | Check the subject carries the identifier fields its data model defines. |
PUBLISH_SCHEME_INCOMPLETE | The identifier resolved to a scheme without a primary key, or a registrar without a namespace. | Complete the scheme and registrar configuration, then issue again. |
PUBLISH_IDENTIFIER_UNKNOWN | No identifier matching the value is registered for the tenant, or the scheme named in identifierSchemeId does not hold that value. | Register the identifier under a scheme, or correct identifierSchemeId. |
PUBLISH_IDENTIFIER_AMBIGUOUS | The value exists under more than one scheme, so the target is not decidable. | Set publishingOptions.identifierSchemeId to the scheme you want to publish under. |
PUBLISH_IDR_UNAVAILABLE | No Identity Resolver service is configured for the scheme, registrar, or tenant. | Ask your operator to configure an IDR service instance. |
PUBLISH_TARGET_UNRESOLVED | The identifier lookup itself failed, so no publish was attempted. | The credential was issued; ask your operator to check the service. |
PUBLISH_LINKS_UNBUILDABLE | The credential links could not be built from the stored credential. | The credential was issued and stored; ask your operator to check the storage response. |
IDR_PUBLISH_FAILED | The Identity Resolver rejected the links. | Check the scheme is registered with the resolver, then issue again once it is. |
IDR_PUBLISH_UNCONFIRMED | The resolver could not be reached or did not answer, so whether the links were registered is unknown. | Ask your operator to check the resolver before issuing again: a second publish of the same links is rejected as a duplicate. |
DB_STATUS_UPDATE_FAILED | The links are live on the resolver, but the stored published status could not be saved. | The credential is discoverable; only the local status is stale. |
ENTITY_LINK_FAILED | The credential could not be linked to its master-data record, which no longer exists. | Optional enrichment only; publishing and the credential itself are unaffected. |
DETAILS_EXTRACTION_FAILED | The credential's name, issuer, subject and validity dates could not be read from it, so they are not recorded against it. | The credential can be retrieved and verified as usual. Only its stored summary is missing. The warning names the correlation ID to quote to your operator, who can find the cause in the logs. |
IDEMPOTENCY_RESPONSE_NOT_RECORDED | The credential was issued and a retry with this key returns it, but the warnings on this response may not be repeated. | A retry with this key returns this credential. The warnings on this response may differ. |
IDEMPOTENCY_RESPONSE_UNREADABLE | The credential was issued by an earlier request with this key, but the response recorded for it could not be read, so any warnings from that response are not repeated here. | The credential itself is unaffected. Quote the correlation ID to your operator, who can find the cause in the logs. |
The IDR entry's description field is taken from the linked primary entity's description, falling back to the entity's name, and then to the link title (publishingOptions.linkTitle, or the data model's name) when no entity is linked, since the resolver requires a non-empty description.
Human verification link: When publishing without an explicit humanVerificationUrl, the published link set includes a link to this Reference Implementation's own verify page. The base is derived from the RI_APP_URL environment variable, which is parsed as a URL with /verify appended to its path (any query or fragment is dropped, a base path is preserved, and a trailing slash is trimmed); for the default http://localhost:3003 the link is http://localhost:3003/verify. RI_APP_URL is configured in the RI's environment (the shipped .env.example and Docker Compose files default it to http://localhost:3003) and is the same base URL that backs the OIDC post-logout redirect (see Identity provider requirements). Supplying humanVerificationUrl overrides the default, for deployments that host verification elsewhere.
A supplied humanVerificationUrl keeps its own query string and fragment, but the RI strips five reserved parameter names from it before adding its own verification payload: uri, digestMultibase, hash, decryptionKey, and q. The RI's own verify page reads those parameters directly, so a supplied URL that already used one of them would otherwise shadow the payload. machineVerificationUrl is not processed this way. It is published exactly as supplied, with no query-string handling.
When the credential was stored encrypted, the published credential link declares encryptionMethod: AES-256, so a consumer reading the resolver's link set can tell the target is encrypted before fetching it. That value is the vocabulary the UNTP Identity Resolver API definition declares for the field (none, AES-128, AES-256) rather than the cipher name; the Pyx Identity Resolver bundled with the Reference Implementation validates against the same list, and a consumer that has fetched the document reads the cipher from the stored envelope's type field (aes-256-gcm), as the Playground does. Neither verification link carries the field, because those links point at verification surfaces rather than at the encrypted document.
The published link does not carry the credential's decryption key. The key is not registered on the Identity Resolver; it is shared out of band, so access to an encrypted credential does not travel with its discovery link (regardless of whether a given resolver is publicly readable). A credential stored encrypted (the storage default) therefore needs its decryption key supplied out of band to verify, and the published link alone verifies a credential stored unencrypted. The issuing tenant can retrieve that decryption key from the credential's library detail and share it through a channel of its choosing. This differs from a link shared directly as a single-link capability, which may embed the key (see the verify page).
RI_APP_URL is validated when the application starts (see Startup), so a deployment that could not build a safe default link fails at boot rather than at request time. Omitting humanVerificationUrl is always a valid request; supplying it overrides the default for deployments that host verification elsewhere.
| Publishing Option | Type | Description |
|---|---|---|
publish | boolean | Whether to publish to the identity resolver |
linkType | string | Link relation type (defaults to the IDR service's configured default link type) |
linkTitle | string | Human-readable title for the link (defaults to the data model name) |
qualifierPath | string | Qualifier path for sub-identifiers, e.g., /10/LOT123/21/SER456 (defaults to /) |
machineVerificationUrl | string | URL for machine-readable verification of the credential. Must be a well-formed HTTP(S) URL without embedded credentials |
humanVerificationUrl | string | URL for human-readable verification of the credential (defaults to ${RI_APP_URL}/verify, this RI's verify page, when publishing). Must be a well-formed HTTP(S) URL without embedded credentials |
hreflang | string[] | Well-formed BCP 47 language tags for the link's target content |
additionalRels | string[] | Additional link relation types to attach beyond linkType |
public | boolean | Whether the published link is publicly resolvable |
accessRole | string[] | UNTP access roles allowed to retrieve the published links, from the UNTP access role vocabulary (e.g. untp:accessRole#Regulator); attached to the credential and human verification links |
Issuance Endpoints
Issue a Credential
POST /api/v1/credentials
Validates, signs, stores, and optionally publishes a verifiable credential. Returns the credential's database ID and any advisory warnings.
Request body fields:
| Field | Type | Required | Description |
|---|---|---|---|
credentialPayload | object | Yes | Full credential payload conforming to the UNTP schema for the specified type and version |
credentialType | string | Yes | Registered data model type (e.g., DigitalProductPassport) |
version | string | Yes | Registered data model version (e.g., 0.6.1) |
storageOptions.serviceInstanceId | string | No | Explicit storage service instance. If provided, it must be accessible to the tenant (its own, or a system default); otherwise the request is rejected with a 404 |
storageOptions.encrypt | boolean | No | Whether to encrypt (default: true) |
publishingOptions.publish | boolean | No | Whether to publish to IDR |
publishingOptions.linkType | string | No | Link relation type |
publishingOptions.linkTitle | string | No | Link title (defaults to data model name) |
publishingOptions.identifierSchemeId | string | No | Scheme to publish under, needed only when the credential's identifier value exists under more than one scheme |
publishingOptions.qualifierPath | string | No | Qualifier path (default: /) |
publishingOptions.machineVerificationUrl | string | No | Machine verification URL |
publishingOptions.humanVerificationUrl | string | No | Human verification URL (defaults to ${RI_APP_URL}/verify when publishing) |
publishingOptions.hreflang | string[] | No | BCP 47 language tags for the link's target content |
publishingOptions.additionalRels | string[] | No | Additional link relation types beyond linkType |
publishingOptions.public | boolean | No | Whether the published link is publicly resolvable |
publishingOptions.accessRole | string[] | No | UNTP access roles governing who the published links are surfaced to (e.g. untp:accessRole#Regulator) |
Every field is shape-checked at the boundary: a missing or mistyped field is rejected with a 400 that names it, and unknown fields are ignored. The verification URLs must be well-formed HTTP(S) URLs without embedded credentials, hreflang entries must be well-formed BCP 47 language tags, and linkType must not be blank. Passing null for storageOptions or publishingOptions is rejected; omit them instead.
Request headers:
| Header | Required | Description |
|---|---|---|
Idempotency-Key | No | A non-blank string of at most 255 characters after trimming, using only printable ASCII. Keys are scoped to the authenticated tenant. |
When the header is present, a retry while the original is still running, including while it publishes, is rejected with 409 and code IDEMPOTENCY_KEY_IN_FLIGHT. Once the original has delivered its response, the same key and the same raw request body replay that 201, warnings included; the recorded-but-undelivered case below is the one exception to warnings coming back. A later request with the same key and a different body is rejected with 422 and code IDEMPOTENCY_KEY_MISMATCH. If the original never delivered a response, a retry after the configured window replays the credential it recorded, or issues afresh only when no credential was recorded. A key whose credential was later removed is free again. Omitting the header leaves issuance unchanged.
A request body over the configured limit returns HTTP 413 with code REQUEST_BODY_TOO_LARGE; see the request body size limit.
Verification Endpoint
Verify a Credential
POST /api/v1/credentials/verify
This endpoint does not require authentication. It is designed for third-party verification of credentials using parameters typically encoded in a QR code or verification link.
Request body fields:
| Field | Type | Required | Description |
|---|---|---|---|
uri | string (URL) | Yes | Storage URI where the credential is stored. Must be HTTP(S) without embedded userinfo credentials. |
digestMultibase | string | No | Expected multibase-encoded digest of the credential content. If provided, the fetched credential's digest is verified against it. |
hash | string | No | Expected SHA-256 hash as 64-character lowercase hex. The value is compared exactly, so uppercase hex is rejected. Accepted for links created before the digest migration. Prefer digestMultibase. |
decryptionKey | string | No | AES-GCM decryption key (64-character hex string). Required for encrypted credentials. |
The endpoint always returns HTTP 200 for a completed verification attempt, even if the credential fails verification. Check the verified field for the outcome. Processing errors that prevent a verification attempt return 422 with a code field:
| Code | Meaning |
|---|---|
INVALID_RESPONSE | The storage URI's response is not valid JSON, or is valid JSON that is not an object (a literal null, an array, or a primitive), before or after decryption. |
DECRYPTION_REQUIRED | The credential is encrypted and no decryptionKey was supplied. The verify page prompts for the key in this case. |
ENVELOPE_INVALID | The stored encrypted envelope is structurally corrupted (wrong IV or auth-tag length). Re-supplying the key will not help. |
DECRYPTION_FAILED | The decryption key does not match the credential. This is almost always a wrong key, but AES-GCM cannot distinguish a wrong key from ciphertext tampered at valid lengths. |
DECRYPTED_NOT_JSON | Decryption succeeded but the content is not valid JSON, so the stored credential is corrupted. |
DIGEST_MISMATCH | The fetched credential does not match the digest in the request. |
UNSUPPORTED_CREDENTIAL_TYPE | The credential is not an EnvelopedVerifiableCredential. |
Upstream failures (storage unreachable, non-2xx, oversized response, VC service failure) return 502 with UPSTREAM_ERROR or VC_SERVICE_ERROR.
The storage URI is fetched through a guarded resolver that validates the hostname against private and reserved ranges on every redirect hop and pins the connection to the validated addresses, so neither a redirect nor a DNS change between check and connect can reach a private network.
Decryption happens on the server, so a decryptionKey travels in the request body. Production deployments must serve this endpoint over HTTPS so the key is protected in transit.
This endpoint reads the shared credential-fetch settings below on every request, and those readers are not cached. If both names of one pair become set after the process started, the next request is answered 500 with an error naming the two conflicting variables. That applies here even though the endpoint is unauthenticated, so an anonymous caller can see the two variable names, though never their values. The remedy is to set the pair to a single name and restart the process, recreating the container where one is in use.
Shared credential-fetch settings
The following settings are shared by verification, external registration and the supplier-source check used by re-verification. The private-address setting also controls the existing stored-address URL checks on registrar, identifier-link, data-model, service and credential publishing routes.
| Variable | Default | Description |
|---|---|---|
FETCH_ALLOW_PRIVATE_URLS | false | Permits private or reserved destinations for caller-supplied credential retrieval and relaxes the stored-address checks for registrars, identifier links, data models, service URLs and credential publishing URLs. The credential fetch still parses the URL, requires a name that resolves, follows and re-checks each redirect hop, pins the connection to the resolved addresses and enforces the response-size limit. The connection is pinned to the set of addresses the name resolved to at validation time. Node's address selection tries those addresses within the request budget, so a localhost that resolves to both ::1 and 127.0.0.1 reaches whichever listens. Use it only for local development: with it on, an anonymous caller of the verify endpoint can make the server fetch any address it can route to, including the cloud metadata service. Only exact lowercase true enables it, and it does not remove http(s) scheme or userinfo validation. |
FETCH_MAX_RESPONSE_SIZE | 10485760 (10 MB) | Maximum response size in bytes. A value the parser cannot read as a positive number falls back to the default rather than failing startup. |
FETCH_TIMEOUT_MS | 10000 | Time budget for fetching the credential, in milliseconds, covering the wait for DNS, connect, redirects and body (maximum 120000). Also applies when registering or re-verifying an external library credential. Startup fails when the value is not a positive integer within that ceiling. |
Old names remain supported during RI v0.5 and produce a startup warning when used alone. Setting both names for one setting, including equal values, fails startup. See the startup configuration table and the v0.5 migration guide for the complete mapping and conflict rules.
The redirect chain is capped at three additional hops on both settings. That cap is fixed, not an environment variable, and a chain that exceeds it returns 502 with UPSTREAM_ERROR.
Delete a Credential
DELETE /api/v1/credentials/{id}
Deletes a credential this service issued, using the credential record id returned by issuance. The library record, its verification history and its issuance idempotency claim are removed in one transaction. The Reference Implementation then deletes the durable copy of the signed artefact from the storage instance, bucket and object id it recorded at issuance, and answers once that attempt has finished.
Deleting a credential does not revoke it. A copy that was already shared with a verifier remains verifiable against its status list. Revocation on delete is planned for a later release. Identifier links published to the Identity Resolver for the credential are not removed and will resolve to a missing artefact.
The lookup is tenant-scoped. A record that exists only in another tenant, one that was already deleted and an id that never existed all answer the same empty 204, so repeating a delete is safe. An external library record in the caller's tenant is refused; it is deleted with DELETE /api/v1/library/{id}.
The durable-copy deletion is best effort and never changes the response. A copy that cannot be removed is left in place and reported in the operator log with the recorded coordinates: an unreachable storage service, a refused delete, or a credential issued before v0.5 recorded where its copy lives. Repeating the request does not retry the copy: the record is already gone, so the repeat answers 204 without touching storage, and the orphaned object is reclaimed by an operator from the logged coordinates. A crash between the commit and that log line leaves the object with no logged coordinates at all; the storage service's own listing is then the only route to it. Nothing resurrects the database record once its transaction has committed. The issuance idempotency claim is removed with the record, so the key becomes free again, as Issue a Credential describes.
Responses:
204with no body: the credential was deleted by this call, was deleted earlier, never existed, or exists only in another tenant.401when the request carries no valid token.403 EXTERNAL_RECORD_NOT_DELETABLE_HEREwhen the id names an external library record, with the messageThis id is an external library record; delete it with DELETE /api/v1/library/{id}.Authentication can separately answer the shared tenant-assignment refusal.- Sanitised
500when the transaction failed and rolled back, or when its commit outcome could not be confirmed. The request is safe to repeat in both cases.
Retired read routes
List Credentials (retired)
GET /api/v1/credentials
This route is retired and returns 410 Gone after authentication and tenant resolution succeed, with code: ROUTE_RETIRED. Use the Library API for the combined inventory.
Get a Credential (retired)
GET /api/v1/credentials/{id}
This route is retired and returns 410 Gone after authentication and tenant resolution succeed, with code: ROUTE_RETIRED. Use Library API detail with the same record id for the stored credential and its custody fields.