Skip to main content

REST API

REST API - Backend​

Base URL: http://localhost:3000

Below are the primary endpoints with purpose, request/response shapes, and example calls.

POST /credentials — Issue a credential​

Creates, signs, and persists a credential. Returns the full signed credential.

Responses

  • 201 Created with the issued credential JSON.
  • 400 Bad Request on validation errors (e.g., missing required fields, extra properties).

Request body

{
  "type": "Car Membership3",
  "issuer": "did:web:acme-gym",
  "subject": "did:example:alice",
  "claims": {
    "tier": "gold",
    "expiresOn": "2025-12-31"
  }
}

Sample Response

{
    "id": "0b7ab0c1-4bbd-409f-8588-8b1a6ce31022",
    "type": "Car Membership3",
    "issuer": "did:web:acme-gym",
    "subject": "did:example:alice",
    "claims": {
        "tier": "gold",
        "expiresOn": "2025-12-31"
    },
    "issuedAt": "2025-11-25T14:25:46.192Z",
    "signature": "sig",
    "algorithm": "ed25519",
    "publicKey": "pubkey"
}

Sample call

curl -X POST http://localhost:3000/credentials \
  -H "Content-Type: application/json" \
  -d '{
  "type": "Car Membership3",
  "issuer": "did:web:acme-gym",
  "subject": "did:example:alice",
  "claims": {
    "tier": "gold",
    "expiresOn": "2025-12-31"
  }
}'

GET /credentials — List credentials​

Returns every stored credential.

Responses

  • 200 OK with an array of credential objects (empty array when none exist).

Sample call

curl http://localhost:3000/credentials

Sample Response

[
    {
        "id": "e44d03ba-69c0-4a87-ae89-64c90694969f",
        "type": "Car Membership3",
        "issuer": "did:web:acme-gym",
        "subject": "did:example:alice",
        "claims": {
            "tier": "gold",
            "expiresOn": "2025-12-31"
        },
        "issuedAt": "2025-11-25T13:13:46.861Z",
        "signature": "+Hjw6rgMNjTCLjLK5sDvg9tNKDrUp5fYIH2AIsb7XOgZlJBVVS/aa5u11Zi5scFzCiTX+SQI6gFJGs6W5L8uCA==",
        "algorithm": "ed25519",
        "publicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAtCWaX/Seu/r8PnVvVKnmTRumlsru9xfL1CAF4KSFXxc=\n-----END PUBLIC KEY-----\n"
    },
    {
        "id": "ab8d24ad-0400-47dd-8391-792a628df3b7",
        "type": "Car Membership3",
        "issuer": "did:web:acme-test",
        "subject": "did:example:alice",
        "claims": {
            "tier": "gold",
            "expiresOn": "2025-12-31"
        },
        "issuedAt": "2025-11-25T13:33:59.942Z",
        "signature": "sig",
        "algorithm": "ed25519",
        "publicKey": "key"
    },
    {
        "id": "a7b1310e-f56f-46db-8be8-3cdb710aa3bd",
        "type": "Car Membership1",
        "issuer": "did:web:acme-cars",
        "subject": "did:example:alice",
        "claims": {
            "tier": "gold",
            "expiresOn": "2025-12-31"
        },
        "issuedAt": "2025-11-25T14:24:36.219Z",
        "signature": "sig",
        "algorithm": "ed25519",
        "publicKey": "key"
    },
    {
        "id": "0b7ab0c1-4bbd-409f-8588-8b1a6ce31022",
        "type": "Car Membership2",
        "issuer": "did:web:acme-test",
        "subject": "did:example:alice",
        "claims": {
            "tier": "gold",
            "expiresOn": "2025-12-31"
        },
        "issuedAt": "2025-11-25T14:25:46.192Z",
        "signature": "sig",
        "algorithm": "ed25519",
        "publicKey": "key"
    }
]

GET /credentials/:id — Fetch credential by ID​

Retrieves a specific credential. Returns 404 if not found.

Responses

  • 200 OK with the credential object.
  • 404 Not Found if the credential does not exist.

Sample call

curl http://localhost:3000/credentials/<credential-id>

Sample Response With id in backed

{
    "id": "e44d03ba-69c0-4a87-ae89-64c90694969f",
    "type": "Car Membership3",
    "issuer": "did:web:acme-gym",
    "subject": "did:example:alice",
    "claims": {
        "tier": "gold",
        "expiresOn": "2025-12-31"
    },
    "issuedAt": "2025-11-25T13:13:46.861Z",
    "signature": "sig",
    "algorithm": "ed25519",
    "publicKey": "pubkey"
}

When id not found

{
    "message": "Credential e44d03ba-69c0-4a87-ae89-64c90694969fs was not found",
    "error": "Not Found",
    "statusCode": 404
}

POST /credentials/verify — Verify a credential​

Validates an externally provided credential JSON (can be from the store or external source). Returns { "isValid": boolean }.

Responses

  • 200 OK with { "isValid": true|false }.
  • 400 Bad Request on validation errors (missing/extra fields).

Request body (example)

{
    "id": "e44d03ba-69c0-4a87-ae89-64c90694969f",
    "type": "Car Membership3",
    "issuer": "did:web:acme-gym",
    "subject": "did:example:alice",
    "claims": {
        "tier": "gold",
        "expiresOn": "2025-12-31"
    },
    "issuedAt": "2025-11-25T13:13:46.861Z",
    "signature": "+Hjw6rgMNjTCLjLK5sDvg9tNKDrUp5fYIH2AIsb7XOgZlJBVVS/aa5u11Zi5scFzCiTX+SQI6gFJGs6W5L8uCA==",
    "algorithm": "ed25519",
    "publicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAtCWaX/Seu/r8PnVvVKnmTRumlsru9xfL1CAF4KSFXxc=\n-----END PUBLIC KEY-----\n"
}

Sample call

curl -X POST http://localhost:3000/credentials/verify \
  -H "Content-Type: application/json" \
  -d @credential.json   # or inline the JSON above

Sample Response When signature is valid

{
    "isValid": true
}

When signature is not valid

{
    "isValid": false
}

When invalid request ( for example tsype invalid property as added)

{
    "message": [
        "property tsype should not exist",
        "type should not be empty",
        "type must be a string"
    ],
    "error": "Bad Request",
    "statusCode": 400
}

DELETE /credentials/:id — Delete a credential​

Deletes a credential by ID. Returns 204 No Content on success, 404 if missing.

Responses

  • 204 No Content when deletion succeeds.
  • 404 Not Found if the credential does not exist.

Sample call

curl -X DELETE -i http://localhost:3000/credentials/<credential-id>

Sample Response When record is deleted

- `204 No Content` when deletion succeeds.

When record not found

{
    "message": "Credential ab8d24ad-0400-47dd-8391-792a628df3b7s was not found",
    "error": "Not Found",
    "statusCode": 404
}

Notes​

  • Global validation is enabled with whitelist and forbidNonWhitelisted; unexpected properties trigger 400 responses.
  • Keys and credentials live in backend-veri-wallet/data/; deleting it resets state and regenerates the signing key pair on next start.