OpenAPIs (1.2.8)

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" }

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).

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.

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.

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.

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).

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.

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.