Skip to main content

API Specifications

Available endpoints and methods:​

Keys​

  • GET /generate-keypair: Generate a new public/private keypair.

Summary:

Generates a new cryptographic keypair consisting of a public key and a private key. This keypair can be used for cryptographic operations such as encryption, signing, or verification.

Description:

This endpoint generates a new public and private keypair using a cryptographically secure algorithm. The generated keys are returned to the client. The private key must be stored securely by the client, as it will not be retrievable again from the server. The public key can be shared or used for encryption or verification purposes.

API Flow:

  1. Client Request: The client sends a GET request to /generate-keypair to generate a new cryptographic keypair.
  2. Server Action: The server generates the keypair using a secure algorithm.
  3. Success Response: The server returns the public and private keys to the client.
  4. Error Response: If an error occurs, the server returns a 500 status code with an error message.

DIDs​

  • POST /dids: Create a new Decentralized Identifier (DID).

Summary:

Creates a new Decentralized Identifier (DID) using the specified method and public key. DIDs are unique identifiers that allow individuals or organizations to control their digital identity.

Description:

This endpoint allows the client to create a new DID by specifying the method (e.g., earthid, key) and a public key. Once created, the DID can be used for identity management and cryptographic operations.

API Flow:

  1. Client Request: The client sends a POST request with the public key and DID method.
  2. Server Action: The server generates a new DID and returns it to the client.
  3. Success Response: The DID is successfully created.
  4. Error Response: If an error occurs (e.g., invalid public key), the server returns a 400 or 500 status code.
  • GET /dids/{did}: Retrieve a DID Document by its DID.

Summary:

Retrieves the DID Document associated with the provided DID.

Description:

This endpoint allows the client to retrieve the DID Document containing the public keys, authentication methods, and other associated information for a Decentralized Identifier (DID).

API Flow:

  1. Client Request: The client sends a GET request with the DID as a path parameter.
  2. Server Action: The server retrieves the associated DID Document from storage.
  3. Success Response: The DID Document is successfully returned.
  4. Error Response: If the DID is not found, the server returns a 404 status code.

Verifiable Credentials​

  • POST /vc-templates: Create a new Verifiable Credential Template.

Summary:

Creates a new Verifiable Credential (VC) template that defines the structure, attributes, and metadata for issuing credentials.

Description:

This endpoint allows the client to define a new VC template that will be used for issuing credentials. The template includes the credential attributes, issuer, and expiration policy.

API Flow:

  1. Client Request: The client sends a POST request with the template name, attributes, and issuer DID.
  2. Server Action: The server creates the new template.
  3. Success Response: The template is successfully created.
  4. Error Response: If a template with the same name already exists, a 409 status code is returned.
  • GET /vc-templates: Retrieve a list of all Verifiable Credential Templates.

Summary:

Retrieves a list of all available Verifiable Credential (VC) templates.

Description:

This endpoint returns all the available templates that define the structure and attributes of Verifiable Credentials. Clients can use these templates to issue credentials for various subjects.

API Flow:

  1. Client Request: The client sends a GET request to retrieve all templates.
  2. Server Action: The server returns a list of templates.
  3. Success Response: The list of templates is returned.
  4. Error Response: If an error occurs, a 500 status code is returned.
  • GET /vc-templates/{templateName}: Retrieve a Verifiable Credential Template by its Name.

Summary:

Retrieves a Verifiable Credential (VC) template by its unique name.

Description:

This endpoint allows the client to retrieve a specific VC template by name. The template contains the structure and attributes for issuing credentials.

API Flow:

  1. Client Request: The client sends a GET request with the template name.
  2. Server Action: The server retrieves the specified template.
  3. Success Response: The template is returned successfully.
  4. Error Response: If the template is not found, a 404 status code is returned.
  • PUT /vc-templates/{templateId}: Update an existing Verifiable Credential Template.

Summary:

Updates a specific Verifiable Credential (VC) template by its ID.

Description:

This endpoint allows the client to update the details of an existing VC template, such as its name, attributes, or issuer.

API Flow:

  1. Client Request: The client sends a PUT request with the updated template data.
  2. Server Action: The server updates the template with the new information.
  3. Success Response: The template is updated successfully.
  4. Error Response: If the template is not found, a 404 status code is returned.
  • DELETE /vc-templates/{templateId}: Delete a Verifiable Credential Template.

Summary:

Deletes a specific Verifiable Credential (VC) template by its ID.

Description:

This endpoint allows the client to delete an existing VC template from the system. Once deleted, the template can no longer be used to issue credentials.

API Flow:

  1. Client Request: The client sends a DELETE request with the template ID.
  2. Server Action: The server deletes the template.
  3. Success Response: The template is deleted successfully.
  4. Error Response: If the template is not found, a 404 status code is returned.
  • POST /credentials: Issue a new Verifiable Credential.

Summary:

Issues a new Verifiable Credential (VC) based on the provided template and subject data.

Description:

This endpoint allows the client to issue a new Verifiable Credential using a specific template. The issued credential contains subject data and is cryptographically signed by the issuer.

API Flow:

  1. Client Request: The client sends a POST request with the template ID and subject data.
  2. Server Action: The server issues a new credential based on the template.
  3. Success Response: The credential is issued and returned to the client.
  4. Error Response: If the request data is invalid, a 400 status code is returned.
  • GET /credentials/{credentialId}: Retrieve a Verifiable Credential by its ID.

Summary:

Retrieves a specific Verifiable Credential (VC) by its unique credential ID.

Description:

This endpoint allows the client to retrieve a specific VC using its unique identifier. The credential contains the signed data, subject attributes, and metadata.

API Flow:

  1. Client Request: The client sends a GET request with the credential ID.
  2. Server Action: The server retrieves the credential.
  3. Success Response: The credential is returned successfully.
  4. Error Response: If the credential is not found, a 404 status code is returned.
  • DELETE /credentials/{credentialId}: Revoke a Verifiable Credential.

Summary:

Revokes an issued Verifiable Credential (VC) by its unique credential ID.

Description:

This endpoint allows the client to revoke a previously issued Verifiable Credential. The credential is marked as revoked, and its validity can no longer be verified.

API Flow:

  1. Client Request: The client sends a DELETE request with the credential ID.
  2. Server Action: The server revokes the credential.
  3. Success Response: The credential is revoked successfully.
  4. Error Response: If the credential is not found, a 404 status code is returned.
  • POST /credentials/verify: Verify the integrity of a Verifiable Credential.

Summary:

Verifies the integrity of a Verifiable Credential (VC) by comparing its hash to the hash stored on the Hedera ledger.

Description:

This endpoint verifies a VC by checking its cryptographic proof against the hash stored on the Hedera ledger. The proof ensures that the credential has not been tampered with.

API Flow:

  1. Client Request: The client sends a POST request with the credential data.
  2. Server Action: The server verifies the cryptographic proof.
  3. Success Response: The credential is valid.
  4. Error Response: If the verification fails, a 400 or 500 status code is returned.

Verifiable Presentations​

  • POST /create-vp: Create a new Verifiable Presentation from the provided Verifiable Credentials (VCs).

Summary:

Creates a Verifiable Presentation (VP) by bundling together multiple Verifiable Credentials (VCs).

Description:

This endpoint allows the client to create a Verifiable Presentation (VP) that contains selected attributes from multiple VCs. The VP is cryptographically signed and can be used for proving the authenticity of the included data.

API Flow:

  1. Client Request: The client sends a POST request with the VCs and selected attributes.
  2. Server Action: The server creates the VP and signs it.
  3. Success Response: The VP is created and returned.
  4. Error Response: If the input data is invalid, a 400 status code is returned.
  • POST /verify-vp: Verify a Verifiable Presentation and its disclosed attributes.

Summary:

Verifies a Verifiable Presentation (VP) by checking its cryptographic proof and the disclosed attributes.

Description:

This endpoint verifies the authenticity of a VP by checking its cryptographic proof and the disclosed attributes. The verification ensures that the included credentials and attributes are valid.

API Flow:

  1. Client Request: The client sends a POST request with the VP and disclosed attributes.
  2. Server Action: The server verifies the VP's cryptographic proof.
  3. Success Response: The VP is valid.
  4. Error Response: If the verification fails, a 400 or 500 status code is returned.

Signature​

  • POST /signature/create: Create a digital signature for provided data.

Summary:

Generates a digital signature for the provided data using the specified private key.

Description:

This endpoint allows the client to generate a digital signature for a piece of data using the specified private key. The signature can be used to prove the authenticity of the data.

API Flow:

  1. Client Request: The client sends a POST request with the data and private key.
  2. Server Action: The server generates the digital signature.
  3. Success Response: The signature is returned to the client.
  4. Error Response: If the input data is invalid, a 400 status code is returned.
  • POST /signature/verify: Verify a digital signature using the public key and original data.

Summary:

Verifies a digital signature by comparing it to the original data and public key.

Description:

This endpoint allows the client to verify a digital signature by comparing it to the original data and the public key of the signer.

API Flow:

  1. Client Request: The client sends a POST request with the signature, data, and public key.
  2. Server Action: The server verifies the signature.
  3. Success Response: The signature is valid.
  4. Error Response: If the verification fails, a 400 or 500 status code is returned.

Zero-Knowledge Proof​

  • POST /createZkpToken: Generate a Zero-Knowledge Proof (ZKP) token based on a Verifiable Credential and condition.

Summary:

Creates a Zero-Knowledge Proof (ZKP) token that proves the validity of a Verifiable Credential without revealing the underlying data.

Description:

This endpoint generates a ZKP token based on a Verifiable Credential and a condition (e.g., age > 18). The ZKP allows the client to prove the validity of the condition without disclosing the full credential.

API Flow:

  1. Client Request: The client sends a POST request with the credential and condition.
  2. Server Action: The server generates the ZKP token.
  3. Success Response: The ZKP token is returned to the client.
  4. Error Response: If the input data is invalid, a 400 or 500 status code is returned.
  • POST /verifyZkpToken: Verify a Zero-Knowledge Proof (ZKP) token.

Summary:

Verifies the authenticity of a Zero-Knowledge Proof (ZKP) token.

Description:

This endpoint verifies the authenticity of a ZKP token by checking its cryptographic proof against the provided public key and ZKP data.

API Flow:

  1. Client Request: The client sends a POST request with the ZKP token, ZKP data, and public key.
  2. Server Action: The server verifies the ZKP token.
  3. Success Response: The ZKP token is valid.
  4. Error Response: If the verification fails, a 400 or 500 status code is returned.

Resolution​

  • GET /resolve/{did}: Resolve a Decentralized Identifier (DID) and retrieve its associated DID Document.

Summary:

Resolves a Decentralized Identifier (DID) and retrieves the associated DID Document.

Description:

This endpoint allows the client to resolve a DID and retrieve the associated DID Document containing the public keys, authentication methods, and services related to the DID.

API Flow:

  1. Client Request: The client sends a GET request with the DID.
  2. Server Action: The server resolves the DID and returns the DID Document.
  3. Success Response: The DID Document is returned successfully.
  4. Error Response: If the DID is not found, a 404 status code is returned.