Credentials in ISBE
The Spain Blockchain Services Infrastructure (ISBE) implements a Verifiable Credentials (VCs) system compliant with the W3C VC Data Model v2 specification. This system allows entities participating in the network to:
- Issue verifiable credentials to employees and representatives of organizations.
- Accredit delegated issuers through on-chain trust chains.
- Authenticate users in ISBE portals by presenting a credential from their digital wallet instead of a username and password.
This section documents the concepts, schemas, operational flows, and the API of the credential services that ISBE exposes in each environment.
What is a Verifiable Credential in ISBE?
A Verifiable Credential (VC) is a cryptographically signed digital document that binds a set of attributes (claims) to an entity identified by its DID. In ISBE all VCs:
- Are encoded as a signed JWT with the issuer's
assertionMethod. - Comply with the VC Data Model v2 (
@context: ["https://www.w3.org/ns/credentials/v2"]). - Are validated against a JSON Schema published in ISBE's schema repository (
isbe-identity-schemas-repository). - Include a reference to the Trusted Issuers Registry (TIR) via the
termsOfUsefield.
Components of the credential system
ISBE divides credential management into several services:
| Service | Purpose | Documented in |
|---|---|---|
| Credential Issuer | Issue VCs to employees and organization representatives. | This section (issuance flow + API) |
| Credential IDP | Authenticate users in ISBE portals via VC presentation (QR + wallet). | This section (verification flow + API) |
| Trusted Issuers Registry (TIR) | Publish the accreditations that authorize each issuer. | Trust Chain section (this section) |
| Schema Repository | Host the JSON Schemas for each VC type. | isbe-identity-schemas-repository |
| DID Registry | Resolve issuers' public keys to verify VC signatures. | Identity section |
Structure of this section
- Key concepts — VC type hierarchy, mandatory fields, proof format.
- Trust chain — RTAO, TAO, TI, TIR and how accreditations are registered.
- Issuance flow — How the Issuer issues VCs to representatives and employees.
- Verification flow — How the IDP authenticates users with VCs via QR code.
- Environments — PRE and PRO URLs for the Issuer and the IDP.
- API Reference — Detailed documentation for each endpoint of the Issuer and the IDP.
- Troubleshooting — Common errors and how to resolve them.
To issue credentials you need:
- An active ISBE DID registered in the corresponding network (see DID → DID Onboarding section).
- The DID registered in the Trusted Issuers Registry (TIR) as an authorized issuer for the VC type you want to issue.
- Access to the ISBE portal of the target environment with a representative credential (or direct API access to the Issuer with a valid Keycloak token).
Throughout this section, placeholders such as <TOKEN>, <DID>, or <ORG_IDENTIFIER> are used. Replace them with actual values before running the commands.