OpenAPIs (1.2.8)
VIDcredentials Studio provides a comprehensive suite of APIs for issuing and verifying credentials. The platform supports two distinct workflows for credential issuance: a custom workflow and a workflow based on OpenID for Verifiable Credentials (OIDC4VC). Each workflow is designed to cater to different use cases and requirements for issuing credentials.
To use the VIDcredentials Studio API, integrators must authenticate their entities. This involves generating a key pair using elliptic curves or RSA. The authentication process ensures that only authorized entities can access the API and perform credential issuance and verification.
- Generate Key Pair: Integrators need to generate a key pair using elliptic curves (e.g., secp256k1) or RSA. The private key is used to sign authentication requests, while the public key is registered with VIDcredentials Studio.
- Authenticate Client: Integrators authenticate by sending a signed JWT containing the client assertion to the authentication endpoint.
Endpoint: POST /authentication
Request Body:
json { "clientAssertion": "<signed JWT>", "grantType": "client_credentials", "clientAssertionType": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer", "scope": "studio" }
Authenticate client
Endpoint for client authentication.
Request Body schema: application/jsonrequired
clientAssertion required | string <jwt> A JWT representing the client assertion that must be signed using the client's private key. |
grantType required | string Value: "client_credentials" Type of grant being requested. |
clientAssertionType required | string Value: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer" Type of client assertion being used. |
scope required | string Enum: "studio" "ewallet" "auth_service" "audit_trails" "wallet_api" Scope for authorization. |
Responses
Request samples
- Payload
{- "clientAssertion": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
- "grantType": "client_credentials",
- "clientAssertionType": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
- "scope": "studio"
}
Response samples
- 200
{- "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
- "tokenType": "Bearer"
}
The Entity Data section provides endpoints for managing and retrieving information about entities within the VIDcredentials Studio API. Integrators can use these endpoints to access details such as entity identifiers, names, and associated decentralized identifiers (DIDs).
Retrieve entity data
This endpoint allows integrators to get the information of the entity with which the integrator has been authorized.
Authorizations:
Responses
Response samples
- 200
{- "id": "73d72395-dfb1-4184-9b0a-d6614e03cb91",
- "name": "Validated ID",
- "dids": "['did:ethr:0x123'],[did:ethr:0x456]",
- "vatNumber": "12345678A"
}
The Entity Credential types section includes endpoints for managing and retrieving information about credential types supported by VIDcredentials Studio. Integrators can use these endpoints to access details such as credential type identifiers, supported types, formats, and metadata.
Get Credential Types
This endpoint retrieves a list of available credential types supported by VIDcredentials Studio. The response includes details for each credential type, such as a unique identifier (ID) and the type's name. Integrators can use this information to understand the available credential types for further interactions.
Authorizations:
Responses
Response samples
- 200
[- {
- "id": "73d72395-dfb1-4184-9b0a-d6614e03cb91",
- "type": "['VerifiableCredential', 'EmailCredential']",
- "format": "json or jwt",
- "entityId": "25d428db-ef37-471d-9dfe-92f7e4aa9702",
- "template": [
- {
- "name": "email",
- "fieldType": "email"
}
], - "expiration": {
- "expires": false
}, - "metadata": {
- "color": "#FD6842",
- "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAALQAAAC4CAYAAABKD8ZJAAAACXBIWXMAABYlAAAWJQFJ...nC2WUsFKNLDQS5ukIrovI/OuK87xs8RFzrSei6vzP/Z",
- "header": {
- "firstLine": "EmailCredential",
- "secondLine": "email"
}, - "fontColor": "#ffffff"
}
}
]
Get Specific Credential Type
This endpoint retrieves information about a specific credential type based on the provided credential type ID.
Authorizations:
path Parameters
credentialTypeId required | string |
Responses
Response samples
- 200
{- "id": "73d72395-dfb1-4184-9b0a-d6614e03cb91",
- "type": "['VerifiableCredential', 'EmailCredential']",
- "format": "json or jwt",
- "entityId": "25d428db-ef37-471d-9dfe-92f7e4aa9702",
- "template": [
- {
- "name": "email",
- "fieldType": "email"
}
], - "expiration": {
- "expires": false
}, - "metadata": {
- "color": "#FD6842",
- "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAALQAAAC4CAYAAABKD8ZJAAAACXBIWXMAABYlAAAWJQFJ...nC2WUsFKNLDQS5ukIrovI/OuK87xs8RFzrSei6vzP/Z",
- "header": {
- "firstLine": "EmailCredential",
- "secondLine": "email"
}, - "fontColor": "#ffffff"
}
}
The Entity Presentation Templates section provides endpoints for managing and retrieving presentation templates. Integrators can use these endpoints to create, retrieve, and manage presentation templates, which define the structure and constraints for verifiable presentations.
Create Presentation Definition for a Template
This endpoint allows integrators to create a presentation definition for a template.
Authorizations:
Request Body schema: application/jsonrequired
scope required | string The scope of the presentation template |
presentationTemplateId required | string The ID of the presentation template |
required | object (PresentationDefinitionDto) |
entityId required | string The ID of the entity |
Responses
Request samples
- Payload
{- "scope": "example-scope",
- "presentationTemplateId": "44c991b0-b30e-4537-a34c-c96de30193a3",
- "presentationDefinition": {
- "id": "example-presentation-definition",
- "input_descriptors": [
- {
- "id": "age-verification",
- "name": "Age Verification",
- "purpose": "To verify the age of the user",
- "format": {
- "jwt_vc": {
- "alg": [
- "ES256",
- "RS256"
]
}
}, - "constraints": {
- "fields": [
- {
- "path": [
- "$.vc.credentialSubject.age"
], - "id": "age",
- "name": "Age",
- "purpose": "To verify the age of the user",
- "filter": {
- "type": "number",
- "minimum": 18
}
}
]
}
}
]
}, - "entityId": "25d428db-ef37-471d-9dfe-92f7e4aa9702"
}
Get Specific Presentation Template
This endpoint retrieves information about a specific presentation template based on the provided presentation template ID.
Authorizations:
path Parameters
presentationTemplateId required | string |
Responses
Response samples
- 200
{- "scope": "example-scope",
- "presentationDefinition": { }
}
The Entity Redirect URIs section provides endpoints for managing and retrieving redirect URIs used in the OpenID Connect for Verifiable Presentations (OIDC4VP) protocol. Integrators can use these endpoints to register, retrieve, and delete redirect URIs for OIDC4VP flows.
Register a new redirect uri
Once the user has presented a credential with the wallet, the integrator may be interested to redirect the user wallet (same device flow). This redirection is based on a redirect uri controlled and managed by integrators in order to protect users' redirection. Integrators that pretend to redirect users wallets once the presentation is performed must previously register their redirect uris using this endpoint.
Authorizations:
Request Body schema: application/jsonrequired
redirectUri required | string Redirect uri to register |
Responses
Request samples
- Payload
{
}
Delete an existing redirect uri
Integrators can delete already registered redirect uris for the OIDC4VP flow. Once a redirect uri is deleted, it will not be available for the presentation flow anymore.
Authorizations:
Request Body schema: application/jsonrequired
redirectUri required | string Redirect uri to delete |
Responses
Request samples
- Payload
{
}
The Credential Status section provides endpoints for checking the status of credentials issued within VIDcredentials Studio. Integrators can use these endpoints to retrieve the current status of a credential based on its issuance ID.
The Credential Workflow section includes endpoints for managing the credential issuance process within VIDcredentials Studio. Integrators can use these endpoints to create credential requests, orders, and issue credentials to decentralized identifiers (DIDs).
Create Credential Request
Integrators can use this endpoint to initiate a credential request. The request includes issuance ID, credential type ID, payload, recipient's email, callback URL, language preference, and details for identity verification, such as type and requested information.
Authorizations:
Request Body schema: application/jsonrequired
issuanceId required | string ID of credential issuing process. Can be random in order to not coincide with other issuing processes. |
credentialTypeId required | string Credential type ID |
payload required | object The content of the credentialSubject. This payload must comply with the same data structure of the credentialType of the credential that is being issued. Note that if there's an id field in the credentialSubject, this id has to be the did of the subject of the credential, following the W3C standard. |
email required | string The email of the recipient of the credential |
callbackUrl required | string URL where the credential request creation data will be sent (Not implemented) |
language required | string The language in which the user will receive the email to accept and receive the credential |
entityDid | string The did of the entity issuing the credential |
required | object (IdentityVerificationMethod) |
Responses
Request samples
- Payload
{- "issuanceId": "72587765-b999-43ce-bdc2-80ac26619d84",
- "credentialTypeId": "44c991b0-b30e-4537-a34c-c96de30193a3",
- "payload": {
- "email": "test@test.com"
}, - "email": "test@gmail.com",
- "callbackUrl": "string",
- "language": "en",
- "entityDid": "did:ethr:0x03fdd57adec3d438ea237fe46b33ee1e016eda6b585c3e27ea66686c2ea5358479",
- "identityVerificationMethod": {
- "type": "EmailCredential",
- "userData": {
- "userName": "Alice",
- "userLegalId": "12345678D"
}, - "requestedInfo": [
- {
- "path": "email",
- "value": "test@test.com"
}
]
}
}
Create Credential Order
Integrators can utilize this endpoint to create a credential order, specifying issuance ID, credential type ID, recipient's email, payload, identity verification details, and language preference. This endpoint facilitates the streamlined initiation of credential creation processes within VIDcredentials Studio.
Authorizations:
Request Body schema: application/jsonrequired
issuanceId required | string ID of credential issuing process. Can be random in order to not coincide with other issuing processes. |
credentialTypeId required | string Credential type ID |
email required | string The email of the recipient of the credential |
payload required | object The content of the credentialSubject. This payload must comply with the same data structure of the credentialType of the credential that is being issued. Note that if there's an id field in the credentialSubject, this id has to be the did of the subject of the credential, following the W3C standard. |
language required | string The language in which the user will receive the email to accept and receive the credential |
entityDid | string The did of the entity issuing the credential |
required | object (IdentityVerificationMethod) |
Responses
Request samples
- Payload
{- "issuanceId": "72587765-b999-43ce-bdc2-80ac26619d84",
- "credentialTypeId": "44c991b0-b30e-4537-a34c-c96de30193a3",
- "email": "test@gmail.com",
- "payload": {
- "email": "test@test.com"
}, - "language": "en",
- "entityDid": "did:ethr:0x03fdd57adec3d438ea237fe46b33ee1e016eda6b585c3e27ea66686c2ea5358479",
- "identityVerificationMethod": {
- "type": "EmailCredential",
- "userData": {
- "userName": "Alice",
- "userLegalId": "12345678D"
}, - "requestedInfo": [
- {
- "path": "email",
- "value": "test@test.com"
}
]
}
}
Issue Credential to did
This endpoint allows integrators to create credentials within VIDcredentials Studio. It requires details such as issuance ID, entity decentralized identifier (DID), credential type ID, recipient DID, and payload. Optionally, integrators can include self-attested parameters and set an expiration date for the credential.
Authorizations:
Request Body schema: application/jsonrequired
issuanceId required | string ID of credential issuing process. Can be random in order to not coincide with other issuing processes. |
entityDid | string The did of the entity issuing the credential |
credentialTypeId required | string ID of the credential type |
recipientDid required | string The did of the recipient of the credential |
payload required | object The content of the credentialSubject. This payload must comply with the same data structure of the credentialType of the credential that is being issued. Note that if there's an id field in the credentialSubject, this id has to be the did of the subject of the credential, following the W3C standard. |
selfAttestedParams | string Proof of user identification |
expirationDate | number The credential's expiration date specified in number of days |
Responses
Request samples
- Payload
{- "issuanceId": "72587765-b999-43ce-bdc2-80ac26619d84",
- "entityDid": "did:ethr:0x03fdd57adec3d438ea237fe46b33ee1e016eda6b585c3e27ea66686c2ea5358479",
- "credentialTypeId": "44c991b0-b30e-4537-a34c-c96de30193a3",
- "recipientDid": "did:ethr:0x613b55c21F0e7ff2994404A3f32d5234Fb2C6216",
- "payload": {
- "email": "test@test.com"
}, - "selfAttestedParams": "string",
- "expirationDate": 1
}
OpenID for Verifiable Credentials (OIDC4VC) Workflow
The OIDC4VC workflow leverages the OpenID Connect protocol to streamline the credential issuance process. It supports two flows: Pre-Authorization Flow and Authorization Flow.
- Issue Credential with Pre-Authorization Flow
- Issue Credential with Authorization Flow
Both workflows are designed to ensure secure and efficient credential issuance, providing different integration needs and scenarios.
Issue Credential with Pre-Authorization Flow in OpenID4VC
Pre-Authorization Flow is a method that allows issuers to issue verifiable credentials to holders without requiring an interactive authentication step at the time of credential issuance. This flow is particularly useful for scenarios where the holder has already been authenticated beforehand.
How the Pre-Authorization Flow Works
Issuer Generates a Pre-Authorized Token
- The issuer creates a credential issuance request and generates a pre-authorization token.
- This token is used to authenticate the holder during the credential issuance process without requiring the user to log in again.
Issuer Provides Credential Offer
- The issuer sends a credential offer to the holder, typically via a QR code or a deep link.
- This offer contains the pre-authorization token and necessary details for credential issuance.
Holder Accepts the Credential Offer
- The holder scans the QR code or clicks the deep link using a wallet application that supports OIDC4VC.
- The wallet processes the offer and automatically presents the pre-authorization token to the issuer’s credential endpoint.
Credential Issuance Without Additional Authentication
- Since the pre-authorization token was already generated, the issuer does not prompt the holder for authentication again.
- The issuer verifies the token and issues the verifiable credential to the holder's wallet.
Key Benefits of Pre-Authorization Flow
- Seamless User Experience: No need for interactive authentication at the time of issuance.
- Efficient Automation: Useful in automated workflows where authentication happens earlier.
- Secure & Controlled Issuance: The pre-authorization token ensures only the intended holder receives the credential.
Issue Credential with Authorization Flow in OpenID4VC
Authorization Flow is a method that allows issuers to issue verifiable credentials to holders after they have been authenticated. This flow is suitable for scenarios where the holder needs to be authenticated and authorize the issuance of credentials interactively.
How the Authorization Flow Works
Issuer Initiates Credential Request
- The issuer initiates the credential issuance process by sending a request to the holder for the issuance of a verifiable credential.
- The request includes the necessary details, such as the attributes to be included in the credential (e.g., name, qualifications).
- This request triggers the need for user authentication before credential issuance.
Holder Authenticates with OpenID Connect
- The holder authenticates with the OpenID Connect provider to confirm their identity.
- The holder is redirected to the authorization endpoint of the OIDC provider for authentication.
- Upon successful authentication, the provider returns an authorization code, which is exchanged for an ID token and an access token.
Holder Authorizes Credential Issuance
- Once authenticated, the holder is prompted to grant consent for the credential issuance.
- The holder approves the request to issue the verifiable credential by allowing the issuer to access specific claims or attributes.
- The consent ensures that only the holder can authorize the issuance of their credentials.
Credential Issuance by Issuer
- After successful authentication and authorization, the issuer generates the verifiable credential.
- The issuer uses the obtained access token to request the necessary data about the holder.
- Once verified, the issuer issues the verifiable credential, which is delivered to the holder’s wallet.
Key Benefits of Authorization Flow
- Interactive Authentication: Ensures that the holder is properly authenticated and authorizes the issuance process.
- Granular Control: The holder has control over which claims or attributes are shared with the issuer, ensuring privacy.
- Security and Trust: The use of OpenID Connect ensures that the authentication process is secure, while the verifiable credential ensures data integrity and authenticity.
Issue Credential with OIDC4CI with Pre-Authorization Flow
Integrators can use this endpoint to request a Credential Issuance using OIDC Pre-Authorized In Time flow.
Authorizations:
Request Body schema: application/jsonrequired
issuanceId required | string An identifier of the Credential Request. |
credentialTypeId required | string Credential type ID of the type of credential that is requested to be issued. |
credentialSubject required | object The content of the credentialSubject. This payload must comply with the same data structure of the credentialType of the credential that is being issued. Note that if there's an id field in the credentialSubject, this id has to be the did of the subject of the credential, following the W3C standard. |
issuerDid | string If the entity has multiple Dids, the integrator can specify which Did the credential wil be issued with. |
userPin | number The user is issued a PIN over the counter, which serves as a security mechanism. The PIN must be a numeric value ranging from 0 to 99999999. |
notificationUrl | string The integrator can optionally provide a notification callback URL to receive feedback from the API during the credential issuance process. The notificationUrl will receive a POST request containing an object with the fields: notificationType, issuanceResult, and optionally errorMessage. If issuanceResult is OK, the errorMessage will be omitted. The notificationType field indicates the kind of notification being sent—in this case, a "status" notification provides information about the outcome of the issuance process. |
Responses
Request samples
- Payload
{- "issuanceId": "654c0286-1375-4ace-bd64-cf07ab741683",
- "credentialTypeId": "44c991b0-b30e-4537-a34c-c96de30193a3",
- "credentialSubject": {
- "email": "test@test.com"
}, - "issuerDid": "did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbshgsdLPCdgj5UXc4fzK5rJmYxPNXhqvZwsgs8uvF16KmCogWtd8UFCNHX7SnMkhESj7xXjTk8Ah5t72FxZgvXiYdxXuJ3NJeHBp2hx2iFxZPbeWf3sxopzMBJt6yFL8PuN",
- "userPin": 4605,
}
Response samples
- 201
{- "qrBase64": "string",
- "rawCredentialOffer": "string"
}
Issue Credential with OIDC4CI with Authorization Flow
Integrators can use this endpoint to request a Credential Issuance using OIDC Authorization In Time flow.
Authorizations:
Request Body schema: application/jsonrequired
issuanceId required | string An identifier of the Credential Request. |
credentialTypeId required | string Credential type ID of the type of credential that is requested to be issued. |
object (AuthenticationOptions) Specifies the authentication method and scope for the credential issuance process | |
issuerDid | string If the entity has multiple Dids, the integrator can specify which Did the credential wil be issued with. |
notificationUrl required | string The integrator can optionally provide a notification callback URL to receive feedback from the API during the credential issuance process. The notificationUrl will receive a POST request containing an object with the fields: notificationType, issuanceResult, and optionally errorMessage. If issuanceResult is OK, the errorMessage will be omitted. The notificationType field indicates the kind of notification being sent—in this case, a "status" notification provides information about the outcome of the issuance process.
Additionally, if the issuance flow requires the holder to present a credential for authentication, the result of that presentation validation will also be sent to the |
Responses
Request samples
- Payload
{- "issuanceId": "654c0286-1375-4ace-bd64-cf07ab741683",
- "credentialTypeId": "44c991b0-b30e-4537-a34c-c96de30193a3",
- "authenticationOptions": {
- "type": "string",
- "scope": "string"
}, - "issuerDid": "did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbshgsdLPCdgj5UXc4fzK5rJmYxPNXhqvZwsgs8uvF16KmCogWtd8UFCNHX7SnMkhESj7xXjTk8Ah5t72FxZgvXiYdxXuJ3NJeHBp2hx2iFxZPbeWf3sxopzMBJt6yFL8PuN",
}
Response samples
- 201
{- "qrBase64": "string",
- "rawCredentialOffer": "string"
}
Store credential Subject
This endpoint allows integrators to submit the credential subject that will be contained in the credential issued in an OIDC4CI Authorize Flow.
Authorizations:
path Parameters
issuanceId required | string <uuid> The issuance ID of the credential request. |
Request Body schema: application/jsonrequired
credentialSubject required | object The credential subject that will be contained in the credential issued. |
Responses
Request samples
- Payload
{- "credentialSubject": { }
}
Credential Deferred Issuance
This endpoint allows integrators to defer the issuance of a credential in an OIDC4VC flow. By deferring the issuance, integrators can initiate the credential issuance process and complete it at a later time, providing flexibility in scenarios where immediate issuance is not possible or desired. The deferred issuance process ensures that all necessary steps and validations are completed before the credential is issued.
Authorizations:
path Parameters
openidIssuanceId required | string The issuance ID of the credential request. |
header Parameters
Authorization required | string Bearer token for authorization. |
Responses
Response samples
- 200
{- "format": "string",
- "credential": "string",
- "c_nonce": "string",
- "c_nonce_expires_in": 0
}
The Request a Verifiable Presentation section provides endpoints for requesting verifiable presentations using the OpenID Connect for Verifiable Presentations (OIDC4VP) protocol. Integrators can use these endpoints to request verifiable presentations from users, define the presentation constraints, and receive the presented credentials.
Request a Verifiable Presentation with OIDC4VP
Integrators can use this endpoint to request a Verifiable Presentation using OIDC4VP. The request includes the scope of the request, an identifier for the request, and a callback URL where the credentials presented by the user will be sent if the presentation is successful.
Authorizations:
Request Body schema: application/jsonrequired
scope | string The scope that defines the type of presentation to perform. Each scope will be associated with a Presentation Definition that will define the constrains of the presentation. This field is optional, can only be provided if presentationDefinition parameter is not provided. |
presentationDefinition | object A JSON object that defines the constraints, format, and required claims that must be included in the credential presentation. This field is optional, can only be provided if scope parameter is not provided. |
verificationRequestId required | string An identifier of the Presentation Request. |
callbackUrl required | string The callback URL where the credentials presented by the user will be sent.
A POST request will be sent to the
|
redirectUri | string This is where the wallet will be redirected when the oidc4vp flow is finished. Fits extremely well for same device flows. This redirect uri has to be pre-registered by the integrator using the POST into /redirect-uris. This field is optional and if not included the wallet will be redirected nowhere. |
Responses
Request samples
- Payload
{- "scope": "EmailCredential",
- "presentationDefinition": {
- "id": "example-presentation-definition",
- "input_descriptors": [
- {
- "id": "age-verification",
- "format": {
- "jwt_vc": {
- "alg": [
- "ES256",
- "RS256"
]
}
}, - "constraints": {
- "fields": [
- {
- "path": [
- "$.vc.credentialSubject.age"
], - "filter": {
- "type": "number",
- "minimum": 18
}
}
]
}
}
]
}, - "verificationRequestId": "654c0286-1375-4ace-bd64-cf07ab741683",
}
Response samples
- 201
{- "qrBase64": "string",
- "rawOpenid4vp": "string"
}