REST API

ESSIF REST API functions.

The ESSIF API exposes the necessary endpoints for running the ESSIF specific flows between Issuers (incl. ESSIF Onboarding Services), Holders and Verifiers.

Aligned with the ESSIF terminology, the API is grouped by the User Wallet (wallet API for consumers / natural persons) and Enterprise Wallet (wallet API for organisations / legal entities).

Note that the EBSI/ESSIF specifications are expected to evolve which will be reflected in continuous updates of the proposed APIs.

The following functions are available:

onboard - EBSI onboarding flow, requests a Verifiable Authorization from EOS
authorize - ESSIF authorization flow
register did - registers DID on the EBSI blockchain
create timestamp - creates a timestamp in EBSI ledger
load timestamp by id - loads a timestamp by the timestamp id
load timestamp by hash - loads a timestamp by the transaction hash

Onboard

The /v1/client/onboard endpoint onboards the specified DID to the EBSI blockchain. It runs the ESSIF onboard API and requires a Bearer token, which can be acquired from https://app.preprod.ebsi.eu/users-onboarding.

curl -X 'POST' \
  'https://essif.ssikit.walt.id/v1/client/onboard' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '<request-body>'

{
    "bearerToken": "string",
    "did": "string"
}

The VerifiableAuthorization credential string

E.g. Onboard the did = did:ebsi:zYubw2L8tCZSKKpAcMmCY2Q.

curl -X 'POST' \
  'https://essif.ssikit.walt.id/v1/client/onboard' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "bearerToken": "eyJhbGciOiJFUzI1NksiLCJ0eXAiOiJKV1QifQ.eyJleHAiOjE2NjUzOTc0ODksImlhdCI6MTY2NTM5NjU4OSwiaXNzIjoiZGlkOmVic2k6emNHdnFnWlRIQ3Rramd0Y0tSTDdIOGsiLCJvbmJvYXJkaW5nIjoicmVjYXB0Y2hhIiwidmFsaWRhdGVkSW5mbyI6eyJhY3Rpb24iOiJsb2dpbiIsImNoYWxsZW5nZV90cyI6IjIwMjItMTAtMTBUMTA6MDk6NDZaIiwiaG9zdG5hbWUiOiJhcHAucHJlcHJvZC5lYnNpLmV1Iiwic2NvcmUiOjAuOSwic3VjY2VzcyI6dHJ1ZX19.Qth9uTf4uXoPR9PiykUKyLV6qsOXtG70gJRghRzu9qMtyQmfqVD5hx2YwBgoWF9jebLCcmVtbr1KxVjuNcy1Cg",
  "did": "did:ebsi:zYubw2L8tCZSKKpAcMmCY2Q"
}'

{
    "bearerToken": "eyJhbGciOiJFUzI1NksiLCJ0eXAiOiJKV1QifQ.eyJleHAiOjE2NjUzOTc0ODksImlhdCI6MTY2NTM5NjU4OSwiaXNzIjoiZGlkOmVic2k6emNHdnFnWlRIQ3Rramd0Y0tSTDdIOGsiLCJvbmJvYXJkaW5nIjoicmVjYXB0Y2hhIiwidmFsaWRhdGVkSW5mbyI6eyJhY3Rpb24iOiJsb2dpbiIsImNoYWxsZW5nZV90cyI6IjIwMjItMTAtMTBUMTA6MDk6NDZaIiwiaG9zdG5hbWUiOiJhcHAucHJlcHJvZC5lYnNpLmV1Iiwic2NvcmUiOjAuOSwic3VjY2VzcyI6dHJ1ZX19.Qth9uTf4uXoPR9PiykUKyLV6qsOXtG70gJRghRzu9qMtyQmfqVD5hx2YwBgoWF9jebLCcmVtbr1KxVjuNcy1Cg",
    "did": "did:ebsi:zYubw2L8tCZSKKpAcMmCY2Q"
}

"{\"verifiableCredential\":{\"id\":\"vc:ebsi:authentication#b1a82eb3-9a29-429d-b440-91894ed07720\",\"issuer\":\"did:ebsi:zcGvqgZTHCtkjgtcKRL7H8k\",\"validFrom\":\"2022-10-10T11:35:23Z\",\"credentialSubject\":{\"id\":\"did:ebsi:zYubw2L8tCZSKKpAcMmCY2Q\"},\"credentialSchema\":{\"id\":\"https://api.preprod.ebsi.eu/trusted-schemas-registry/v1/schemas/0x28d76954924d1c4747a4f1f9e3e9edc9ca965efbf8ff20e4339c2bf2323a5773\",\"type\":\"OID\"},\"issuanceDate\":\"2022-10-10T11:35:23Z\",\"expirationDate\":\"2023-04-10T11:35:23Z\",\"@context\":[\"https://www.w3.org/2018/credentials/v1\",\"https://www.w3.org/2018/credentials/examples/v1\",\"https://w3c-ccg.github.io/lds-jws2020/contexts/lds-jws2020-v1.json\"],\"type\":[\"VerifiableCredential\",\"VerifiableAuthorisation\"],\"proof\":{\"type\":\"EcdsaSecp256k1Signature2019\",\"created\":\"2022-10-10T11:35:23Z\",\"proofPurpose\":\"assertionMethod\",\"verificationMethod\":\"did:ebsi:zcGvqgZTHCtkjgtcKRL7H8k#keys-1\",\"jws\":\"eyJhbGciOiJFUzI1NksiLCJ0eXAiOiJKV1QifQ..WEwqx6kOJMA5Mk6xZ7uTfkZB8RDnAhnnIWInBH6BlJNjtsbzIfpHyzB11Gh1xWQVejD3i-0jnwxJyHs8m4JtuQ\"}}}"

Authorize

The /v1/client/auth runs the ESSIF authorization flow for the specified did.

curl -X 'POST' \
  'https://essif.ssikit.walt.id/v1/client/auth' \
  -H 'accept: application/json' \
  -H 'Content-Type: text/plain' \
  -d '<request-body>'

The did string

Code 200

E.g. Run the authorization flow for did = did:ebsi:zYubw2L8tCZSKKpAcMmCY2Q.

curl -X 'POST' \
  'https://essif.ssikit.walt.id/v1/client/auth' \
  -H 'accept: application/json' \
  -H 'Content-Type: text/plain' \
  -d 'did:ebsi:zYubw2L8tCZSKKpAcMmCY2Q'

did:ebsi:zYubw2L8tCZSKKpAcMmCY2Q

Register DID

The /v1/client/registerDid endpoint registers the specified DID on the EBSI ledger.

curl -X 'POST' \
  'https://essif.ssikit.walt.id/v1/client/registerDid' \
  -H 'accept: application/json' \
  -H 'Content-Type: text/plain' \
  -d '<request-body>'

The did url string

Code 200

E.g. Register did = did:ebsi:zwdPobJGue3w86Gpqhq5Cni on the EBSI ledger.

curl -X 'POST' \
  'https://essif.ssikit.walt.id/v1/client/registerDid' \
  -H 'accept: application/json' \
  -H 'Content-Type: text/plain' \
  -d 'did:ebsi:zwdPobJGue3w86Gpqhq5Cni'

did:ebsi:zwdPobJGue3w86Gpqhq5Cni

Create timestamp

The /v1/client/timestamp endpoint creates a timestamp on the EBSI ledger, using the provided DID as a key. The data will be written to the data-field of the timestamp.

curl -X 'POST' \
  'https://essif.ssikit.walt.id/v1/client/timestamp' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '<request-body>'

{
    "did": "string",
    "ethDidAlias": "string",
    "data": "string"
}

The transaction hash

E.g. Create a timestamp using did = did:ebsi:zYubw2L8tCZSKKpAcMmCY2Q.

curl -X 'POST' \
  'https://essif.ssikit.walt.id/v1/client/timestamp' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "did": "did:ebsi:zYubw2L8tCZSKKpAcMmCY2Q",
  "data": "my-data"
}'

{
    "did": "did:ebsi:zYubw2L8tCZSKKpAcMmCY2Q",
    "data": "my-data"
}

0x9c60ca0094771afe4093b0e47260eb623d5d18140e188e671cf912609cd0e169

Load timestamp by id

The /v1/client/timestamp/id/{timestampId} endpoint loads the timestamp based on the provided parameter:

timestampId - path parameter (required) - the timestamp id

curl -X 'GET' \
  'https://essif.ssikit.walt.id/v1/client/timestamp/id/{timestampId}' \
  -H 'accept: application/json'

No parameters

The timestamp json object

E.g. Load the timestamp having id = uEiBEtXzl3QXshn5Z1V4dgZVtMlvnx3E1f2IWFDQVqzEv_Q.

curl -X 'GET' \
  'https://essif.ssikit.walt.id/v1/client/timestamp/id/uEiBEtXzl3QXshn5Z1V4dgZVtMlvnx3E1f2IWFDQVqzEv_Q' \
  -H 'accept: application/json'

{
    "blockNumber": 6434223,
    "data": "0x7b2274657374223a202234346239343965322d336661652d343564372d626666392d396464666436663666376134227d",
    "hash": "mEiBsHu0aNKVDJlqfyxS4pFYH4aFW86s0s60uJl+SmJT8aw",
    "href": "https://api.preprod.ebsi.eu/timestamp/v2/timestamps/uEiBEtXzl3QXshn5Z1V4dgZVtMlvnx3E1f2IWFDQVqzEv_Q",
    "timestamp": "2022-10-10T11:51:16.000Z",
    "timestampId": "uEiBEtXzl3QXshn5Z1V4dgZVtMlvnx3E1f2IWFDQVqzEv_Q",
    "timestampedBy": "0x635A4045A3f82d2C5597225614747c02998B112a",
    "transactionHash": "0x9c60ca0094771afe4093b0e47260eb623d5d18140e188e671cf912609cd0e169"
}

Load timestamp by hash

The /v1/client/timestamp/txhash/{txhash} endpoint loads the timestamp based on the provided parameter:

txhash - path parameter (required) - the transaction hash

curl -X 'GET' \
  'https://essif.ssikit.walt.id/v1/client/timestamp/txhash/{txhash}' \
  -H 'accept: application/json'

No parameters

The timestamp json object

E.g. Load the timestamp having the transcation hash 0x9c60ca0094771afe4093b0e47260eb623d5d18140e188e671cf912609cd0e169.

curl -X 'GET' \
  'https://essif.ssikit.walt.id/v1/client/timestamp/txhash/0x9c60ca0094771afe4093b0e47260eb623d5d18140e188e671cf912609cd0e169' \
  -H 'accept: application/json'

{
    "blockNumber": 6434223,
    "data": "0x7b2274657374223a202234346239343965322d336661652d343564372d626666392d396464666436663666376134227d",
    "hash": "mEiBsHu0aNKVDJlqfyxS4pFYH4aFW86s0s60uJl+SmJT8aw",
    "href": "https://api.preprod.ebsi.eu/timestamp/v2/timestamps/uEiBEtXzl3QXshn5Z1V4dgZVtMlvnx3E1f2IWFDQVqzEv_Q",
    "timestamp": "2022-10-10T11:51:16.000Z",
    "timestampId": "uEiBEtXzl3QXshn5Z1V4dgZVtMlvnx3E1f2IWFDQVqzEv_Q",
    "timestampedBy": "0x635A4045A3f82d2C5597225614747c02998B112a",
    "transactionHash": "0x9c60ca0094771afe4093b0e47260eb623d5d18140e188e671cf912609cd0e169"
}

PreviousDID Registration NextUsage / examples

Last updated 1 year ago