Skip to main content

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.

Client authentication

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.

  1. 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.
  2. 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/json
required
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

Content type
application/json
{
  • "clientAssertion": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  • "grantType": "client_credentials",
  • "clientAssertionType": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
  • "scope": "studio"
}

Response samples

Content type
application/json
{
  • "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  • "tokenType": "Bearer"
}

Entity Data

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:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": "73d72395-dfb1-4184-9b0a-d6614e03cb91",
  • "name": "Validated ID",
  • "dids": "['did:ethr:0x123'],[did:ethr:0x456]",
  • "vatNumber": "12345678A"
}

Entity Credential types

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:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Specific Credential Type

This endpoint retrieves information about a specific credential type based on the provided credential type ID.

Authorizations:
bearerAuth
path Parameters
credentialTypeId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "73d72395-dfb1-4184-9b0a-d6614e03cb91",
  • "type": "['VerifiableCredential', 'EmailCredential']",
  • "format": "json or jwt",
  • "entityId": "25d428db-ef37-471d-9dfe-92f7e4aa9702",
  • "template": [
    ],
  • "expiration": {
    },
  • "metadata": {
    }
}

Entity Presentation templates

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:
bearerAuth
Request Body schema: application/json
required
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

Content type
application/json
{
  • "scope": "example-scope",
  • "presentationTemplateId": "44c991b0-b30e-4537-a34c-c96de30193a3",
  • "presentationDefinition": {
    },
  • "entityId": "25d428db-ef37-471d-9dfe-92f7e4aa9702"
}

Get All Presentation Templates

This endpoint retrieves all presentation templates available in VIDcredentials Studio.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Specific Presentation Template

This endpoint retrieves information about a specific presentation template based on the provided presentation template ID.

Authorizations:
bearerAuth
path Parameters
presentationTemplateId
required
string

Responses

Response samples

Content type
application/json
{
  • "scope": "example-scope",
  • "presentationDefinition": { }
}

Entity Redirect uris

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:
bearerAuth
Request Body schema: application/json
required
redirectUri
required
string

Redirect uri to register

Responses

Request samples

Content type
application/json
{}

Get all redirect uris

This endpoint retrieves all the redirect uris registered by an integrator. The array can be empty if all redirect uris have been deleted after been registered.

Authorizations:
bearerAuth

Responses

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:
bearerAuth
Request Body schema: application/json
required
redirectUri
required
string

Redirect uri to delete

Responses

Request samples

Content type
application/json
{}

Credential Status

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.

Get Credential Status

This endpoint allows integrators to retrieve the status of a credential within VIDcredentials Studio. It requires the issuance ID of the credential to get the status of.

Authorizations:
bearerAuth
path Parameters
issuanceId
required
string

Responses

Revoke Credential

This endpoint allows integrators to revoke credentials within VIDcredentials Studio. It requires the issuance ID of the credential to revoke.

Authorizations:
bearerAuth
path Parameters
issuanceId
required
string

Responses

Credential Workflow

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:
bearerAuth
Request Body schema: application/json
required
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

Content type
application/json
{
  • "issuanceId": "72587765-b999-43ce-bdc2-80ac26619d84",
  • "credentialTypeId": "44c991b0-b30e-4537-a34c-c96de30193a3",
  • "payload": {
    },
  • "email": "test@gmail.com",
  • "callbackUrl": "string",
  • "language": "en",
  • "entityDid": "did:ethr:0x03fdd57adec3d438ea237fe46b33ee1e016eda6b585c3e27ea66686c2ea5358479",
  • "identityVerificationMethod": {
    }
}

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:
bearerAuth
Request Body schema: application/json
required
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

Content type
application/json
{
  • "issuanceId": "72587765-b999-43ce-bdc2-80ac26619d84",
  • "credentialTypeId": "44c991b0-b30e-4537-a34c-c96de30193a3",
  • "email": "test@gmail.com",
  • "payload": {
    },
  • "language": "en",
  • "entityDid": "did:ethr:0x03fdd57adec3d438ea237fe46b33ee1e016eda6b585c3e27ea66686c2ea5358479",
  • "identityVerificationMethod": {
    }
}

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:
bearerAuth
Request Body schema: application/json
required
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

Content type
application/json
{
  • "issuanceId": "72587765-b999-43ce-bdc2-80ac26619d84",
  • "entityDid": "did:ethr:0x03fdd57adec3d438ea237fe46b33ee1e016eda6b585c3e27ea66686c2ea5358479",
  • "credentialTypeId": "44c991b0-b30e-4537-a34c-c96de30193a3",
  • "recipientDid": "did:ethr:0x613b55c21F0e7ff2994404A3f32d5234Fb2C6216",
  • "payload": {
    },
  • "selfAttestedParams": "string",
  • "expirationDate": 1
}

Issue credential

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.

  1. Issue Credential with Pre-Authorization Flow
  2. 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

  1. 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.
  2. 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.
  3. 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.
  4. 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

  1. 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.
  2. 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.
  3. 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.
  4. 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:
bearerAuth
Request Body schema: application/json
required
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

Content type
application/json
{
  • "issuanceId": "654c0286-1375-4ace-bd64-cf07ab741683",
  • "credentialTypeId": "44c991b0-b30e-4537-a34c-c96de30193a3",
  • "credentialSubject": {
    },
  • "issuerDid": "did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbshgsdLPCdgj5UXc4fzK5rJmYxPNXhqvZwsgs8uvF16KmCogWtd8UFCNHX7SnMkhESj7xXjTk8Ah5t72FxZgvXiYdxXuJ3NJeHBp2hx2iFxZPbeWf3sxopzMBJt6yFL8PuN",
  • "userPin": 4605,
  • "notificationUrl": "https://example.net/callback"
}

Response samples

Content type
application/json
{
  • "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:
bearerAuth
Request Body schema: application/json
required
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 notificationUrl. In this case, notificationType will be "report", and the payload will include a report attribute describing the outcome of the presentation validation and the types of validation that were performed.

Responses

Request samples

Content type
application/json
{
  • "issuanceId": "654c0286-1375-4ace-bd64-cf07ab741683",
  • "credentialTypeId": "44c991b0-b30e-4537-a34c-c96de30193a3",
  • "authenticationOptions": {
    },
  • "issuerDid": "did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbshgsdLPCdgj5UXc4fzK5rJmYxPNXhqvZwsgs8uvF16KmCogWtd8UFCNHX7SnMkhESj7xXjTk8Ah5t72FxZgvXiYdxXuJ3NJeHBp2hx2iFxZPbeWf3sxopzMBJt6yFL8PuN",
  • "notificationUrl": "https://example.net/callback"
}

Response samples

Content type
application/json
{
  • "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:
bearerAuth
path Parameters
issuanceId
required
string <uuid>

The issuance ID of the credential request.

Request Body schema: application/json
required
credentialSubject
required
object

The credential subject that will be contained in the credential issued.

Responses

Request samples

Content type
application/json
{
  • "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:
bearerAuth
path Parameters
openidIssuanceId
required
string

The issuance ID of the credential request.

header Parameters
Authorization
required
string

Bearer token for authorization.

Responses

Response samples

Content type
application/json
{
  • "format": "string",
  • "credential": "string",
  • "c_nonce": "string",
  • "c_nonce_expires_in": 0
}

Request a Verifiable presentation

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:
bearerAuth
Request Body schema: application/json
required
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 callbackUrl provided in the request. This POST request will include a validation report, indicating the outcome of the presentation validation and the types of validation that were performed. The payload will also include the field notificationType set to "report" to distinguish this message from other types of notifications. The structure of this report includes:

  • globalResult: Overall result of the validation (OK, KO, or NotValidated) and an optional error message.
  • verifiablePresentation: The Verifiable Presentation object provided by the user.
  • credentialsPresentedList: An array of credentials, each containing:
    • verifiableCredential: The raw credential (string or object).
    • verifiableCredentialsDecoded: The decoded credential content.
    • validations: An array of validation results with details such as validation type (Expiration, NotYetValid, Revocation, Schema, CredentialSignature), individual validation result (OK, KO, NotValidated), and an optional error message.
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

Content type
application/json
{
  • "scope": "EmailCredential",
  • "presentationDefinition": {
    },
  • "verificationRequestId": "654c0286-1375-4ace-bd64-cf07ab741683",
}

Response samples

Content type
application/json
{
  • "qrBase64": "string",
  • "rawOpenid4vp": "string"
}