agentapihttp

December 16, 2025 ยท View on GitHub

A lightweight HTTP API for the SSI Agent.

UniCore's HTTP API is currently still in the pre-release stage meaning that the API is still under active development. Breaking changes may occur before the API reaches a stable version.

The current version of the HTTP API is v0.

OpenAPI specification (Swagger UI)

docker run --rm -p 9090:8080 -e SWAGGER_JSON=/tmp/openapi.yaml -v $(pwd):/tmp swaggerapi/swagger-ui

Browse to http://localhost:9090

CORS

If you want to access UniCore's API from a browser, you can set the UNICORE__CORS_ENABLED environment variable to true. This will enable a permissive CORS policy (allow all).

Usage

Below we describe a typical usage of the HTTP API for UniCore.

Issuance

Typical usage of the Issuance of Credentials

Creating a new Credential

POST /v0/credentials

Now there is a new Credential Configuration, we can create our first Credential.

Parameters
  • offerId: REQUIRED: A unique identifier for the Credential Offer. This ID will bind the Credential to the Credential Offer that we will receive later
  • credentialConfigurationId: REQUIRED
  • credential: REQUIRED An object containing the data that will be included in the Credential. This data should adhere to the Credential Definition that was defined in the Credential Configuration. See the Issuance Configuration for more information about how the Credential Configuration is defined.
{
  "offerId": "my-first-offer",
  "credentialConfigurationId": "w3c_vc_credential",
  "credential": {
    "credentialSubject": {
      "first_name": "Ferris",
      "last_name": "Crabman",
      "dob": "1982-01-01"
    }
  }
}

Retrieving the URL-encoded Credential Offer

POST /v0/offers

After creating a new Credential, we can retrieve the Credential Offer. The Credential Offer is a URL-encoded string that can be rendered as a QR-Code which in turn can be scanned with an Identity Wallet.

Parameters
  • offerId: REQUIRED: The ID of the Credential Offer
{
  "offerId": "my-first-offer"
}

Verification

Typical usage of the Verification of Authorization Responses.

Creating a URL-encoded SIOPv2 Authorization Request

POST /v0/authorization_request

Through this endpoint, we can create a URL-encoded Authorization Request that can be rendered as a QR-Code. This QR-Code can be scanned by an Identity Wallet which in turn will answer the Authorization Request.

Parameters
  • nonce: REQUIRED: A unique identifier for the Authorization Request.
  • state: OPTIONAL: A unique string representing the state of the Authorization Request.
{
  "nonce": "this is a nonce"
}

Creating a URL-encoded OID4VP Authorization Request

POST /v0/authorization_request

Through this endpoint, we can create a URL-encoded Authorization Request that can be rendered as a QR-Code. This QR-Code can be scanned by an Identity Wallet which in turn will answer the Authorization Request. The only extra required parameter is the dcql_query which describes the Verifiable Credential(s) that will be requested from the Identity Wallet.

Parameters
  • nonce: REQUIRED: A unique identifier for the Authorization Request.
  • dcql_query: REQUIRED: An object describing the Verifiable Credential(s) that will be requested from the Identity Wallet to ensure a successful Authorization. In most cases, the dcql_query format below will be sufficient for basic credential requests, but additional constraints can be added as needed.
  • state: OPTIONAL: A unique string representing the state of the Authorization Request.
{
  "nonce": "this is a nonce",
  "dcql_query": {
    "credentials": [
      {
        "id": "CredentialQuery",
        "format": "jwt_vc_json",
        "meta": {
          "type_values": [
            ["VerifiableCredential"]
            // ["OpenBadgesCredential"] <-- for OpenBadges
          ]
        },
        "claims": [
          // Extra constraints can be added to the DCQL query
          // {
          //   "path": ["credentialSubject", "first_name"]
          // },
          // {
          //   "path": ["credentialSubject", "last_name"]
          // }
        ]
      }
    ]
  }
}