DID Registry API

The DID Registry API is the HTTP interface that ISBE exposes so that entities can manage their DID directly, without needing to interact with the blockchain at a low level. It is implemented with Node.js / Express and published in each of the three environments.

Current version: v2.0.0 (basepath /api/v1)
Format: OpenAPI 3.0.3
Specification: available as openapi.yaml in the isbe-identity-did-api repository.

URLs by Environment

Environment	Base URL	Swagger UI
PRE	`https://did-registry.pre.portal.redisbe.com`	`/api`
PRO	`https://did-registry.portal.redisbe.com`	`/api/v1`

Transaction Model

The API distinguishes between two types of operations:

1. Queries (`GET`)

Direct reading of the registry. They do not require a signature. They are invoked and the response is the requested data.

GET /api/v1/identifiers — List DIDs.
GET /api/v1/identifiers/{identifier} — Resolve DID Document.

2. Write Operations (`POST /contract/...`)

Any endpoint under /contract/ DOES NOT execute the transaction on-chain. Instead, it returns an unsigned transaction that the client must:

Sign off-chain with its private control key.
Send using POST /api/v1/transactions/send.

This pattern ensures that the API never has access to the users' private keys.

Authentication

Currently, the API does not require standard HTTP authentication (there is no Authorization header). Access control is delegated to the blockchain: only transactions signed by an authorized EOA (DID controller, or the TA in special operations) are accepted by the smart contract.

For special operations such as insertFirstDidDocument, the from EOA must be previously authorized as an onboarding node. Otherwise, the transaction will revert on-chain.

Transaction Response Format

All POST /contract/... endpoints return the same object:

{
  "to": "0x00000000000000000000000000000000000015Be",
  "data": "0x<calldata>",
  "gasLimit": "0x4c4b40",
  "gasPrice": "0xfa0",
  "chainId": "0x8131",
  "nonce": "0xe",
  "value": "0x0",
  "from": "0x<SIGNER_EOA>"
}

All hexadecimal fields are encoded as strings with a 0x prefix (Ethereum JSON-RPC format).

Error Codes

The API uses the standard format:

{
  "error": "validation_error",
  "error_description": "Field 'vMethodId' must be a base64url-encoded 32 bytes string"
}

HTTP Code	Meaning
`200 OK`	Successful operation.
`206 Partial Content`	Transaction sent but receipt is not yet available.
`400 Bad Request`	Invalid body or parameters.
`404 Not Found`	DID not found (in resolution endpoints).
`406 Not Acceptable`	`Accept` header not supported.
`500 Internal Server Error`	Unexpected error in the API or the blockchain network.

Endpoint Map

Endpoint	Tag	Description
`GET /api/v1/identifiers`	Identifiers	List DIDs (paginated).
`GET /api/v1/identifiers/{identifier}`	Identifiers	Resolve DID Document.
`POST /api/v1/contract/insertFirstDidDocument`	DidDocument	Initial registration of a DID.
`POST /api/v1/contract/insertDidDocument`	DidDocument	Replace existing DID Document.
`POST /api/v1/contract/updateAlsoKnownAs`	DidDocument	Update `alsoKnownAs`.
`POST /api/v1/contract/updateBaseDocument`	DidDocument	Update `@context`.
`POST /api/v1/contract/addController`	Controllers	Add controller.
`POST /api/v1/contract/revokeController`	Controllers	Revoke controller.
`POST /api/v1/contract/addVerificationMethod`	Verification Methods	Register new key.
`POST /api/v1/contract/revokeVerificationMethod`	Verification Methods	Revoke key.
`POST /api/v1/contract/expireVerificationMethod`	Verification Methods	Expire key.
`POST /api/v1/contract/rollVerificationMethod`	Verification Methods	Rotate key.
`POST /api/v1/contract/addVerificationRelationship`	Verification Relationships	Associate use with a key.
`POST /api/v1/transactions/send`	Transactions	Send signed transaction.

Each endpoint is documented in detail in the following pages:

URLs by Environment​

Transaction Model​

1. Queries (GET)​

2. Write Operations (POST /contract/...)​

Authentication​

Transaction Response Format​

Error Codes​

Endpoint Map​