Endpoints

Fetch Verifiable Credentials

GET /claims

Headers

Field

Description

Required

Authorization

Base Auth Token

yes

x-did-auth

DID Auth Token

yes

Content-Type

application/json

yes

Request parameters

Parameter

Description

Type

Required

resolver

DID resolver type. Defaults to UniResolverSpherity if not provided.

String

no

subject

DID of a claim subject

String

no

issuer

DID of a claim issuer

String

no

ids

Comma-separated list of claims DIDs

String

no

All stored VCs will be returned if no filter criteria provider i.e. issuer, subject, ids.

Responses

Status

Meaning

Description

Schema

200

OK

VCs successfully retrieved

Inline

403

Forbidden

Missing access rights

Inline

422

Unprocessable Entity

Missing required params

Inline

500

Internal Server Error

Configure wallet failed

Inline

Response schema

Status code - 200

Name

Type

Description

Optional

resolver

String

DID resolver type that was used

no

vcs

Array

Verifiable Credentials that were retrieved

no

Status code - 403/422/500

Name

Type

Description

Optional

statusCode

Number

HTTP status code

no

errorType

String

Error type

no

errorMessage

String

Error message

no

Sign Verifiable Credentials

POST /claims/sign

Headers

Field

Description

Required

Authorization

Base Auth Token

yes

x-did-auth

DID Auth Token

yes

Content-Type

application/json

yes

Request parameters

Field

Description

Type

Required

format

VC format. Defaults to JSON-LD if not provided

String

no

iss

DID of a claim issuer

String

yes

context

Context URI(s)

String/Array

no

type

VC type(s). Can be provided on global level of per claim input, see example.

String/Array

no

sub

DID of a claim subject. Gets applied to all claim that have no dedicated exp specified inside of individual claim input

String

no

exp

UNIX-timestamp of a claim expiration date. Gets applied to all claim that have no dedicated expiration value specified inside of it

Number

no

expiresIn

UNIX-timestamp of an offset (from issuance date) that points to claim expiration date. Gets applied to all claim that have no dedicated expiration value specified inside of it

Number

no

expirationDate

Expiration date in ISO format (ISO 8601). Gets applied to all claim that have no dedicated expiration value specified inside of it

String

no

claims

Claim input for VC creation

Array

yes

id

DID of a claim. Gets generated if not provided

String

no

alias

Human-readable alias for DID of a claim

String

no

sub

DID of a claim subject

String

no

payload

Payload of a claim

Object

no

exp

UNIX-timestamp of a claim expiration date. Gets applied to all claim that have no dedicated expiration value specified inside of it

Number

no

expiresIn

UNIX-timestamp of an offset (from issuance date) that points to claim expiration date. Gets applied to all claims that have no dedicated expiration value specified inside of it

Number

no

expirationDate

Expiration date in ISO format (ISO 8601). Gets applied to all claim that have no dedicated expiration value specified inside of it

String

no

walletConfig

Identity Wallet config

Object

no

-

didMethod

DID method

String

no

"spherity"

apiUrl

API host URL for DID document update

String

no

self host

txsInput

Details for DID document update

Array

no

-

service

DID document service

Object

no

-

name

Service name

String

no

-

value

Service value i.e. URL

String

no

-

validity

Service validity offset in ms

Number

no

-

delegate

DID document delegate

Object

no

-

address

Delegate address i.e. Ethereum address

String

no

generated-on-fly

validity

Delegate validity offset in ms

Number

no

-

newOwner

DID of a new owner

String

no

-

Input for certifiable credential creation

The claim expiration date is omitted if exp, expiresIn, and expirationDate are not provided at the individual claim level or at the global level inside the request body.

Example request - Verifiable Credential as JSON-LD

{
"format": "JSON-LD",
"iss": "did:spherity:0xf9b185e798ef731acba16f94740dc4ca0511f25c",
"type": "eLicense"
"claims": [
{
"id": "did:spherity:0xf9b185e798ef731acba16f94740dc4ca0511f25c",
"sub": "did:spherity:0xf9b185e798ef731acba16f94740dc4ca0511f25c",
"type": "driverLicense"
"payload": {
"FirstName": "Alex",
"LastName": "Yenkalov"
},
"exp": 0,
"expiresIn": 0,
"expirationDate": "string",
"walletConfig": {
"didMethod": "spherity",
"apiUrl": "string"
"txsInput": [
{
"service": {
"name": "string",
"value": "string",
"validity": 0
}
},
{
"delegate":{
"address": "string",
"validity": 0
}
},
{
"newOwner": "string"
}
]
}
}
]
}

Responses

Status

Meaning

Description

Schema

200

OK

VCs successfully signed

Inline

403

Forbidden

Missing access rights

Inline

422

Unprocessable Entity

Missing required params

Inline

500

Internal Server Error

Configure wallet failed

Inline

Field

Description

Type

Optional

resolver

DID resolver type that was used

String

no

vcs

Verifiable Credentials that were issued

Array

no

Response schema

Status code - 200

Name

Type

Description

Optional

resolver

Object

DID resolver type used

no

vcs

Array

Verifiable Credentials

no

Status code - 403/422/500

Name

Type

Description

Optional

statusCode

Number

HTTP status code

no

errorType

String

Error type

no

errorMessage

String

Error message

no

Store Verifiable Credentials

POST /claims

Headers

Field

Description

Required

Authorization

Base Auth Token

yes

x-did-auth

DID Auth Token

yes

Content-Type

application/json

yes

Request parameters

Field

Description

Type

Required

resolver

DID resolver type. Defaults to UniResolverSpherity if not provided.

String

no

claims

Claims input for its storage

Array

yes

jsonld

Verifiable Credential as JSON-LD

Object

no

jwt

Verifiable Credential as JWT

String

no

isPublicAccess

Provide public access to VC

Boolean

no

roles

Role DIDs

Array

no

Each claim object must contain the jsonld or jwt field that represent Verifiable Credential

Public Access has to be set or specific Roles to be assigned for stored VC(s) in order to maintain access.

Roles can be provided inside of body on the top level or individually for claim objects.

In case you want to provide Public Access to VC(s), set isPublicAccess flag to true.

Modifying VC (add/remove VC proofs, remove VC, update VC's DID Document)

  • Public Access grants read capability only

  • To be capable of updating VC's DID Document, one of DIDs that you control has to be a DID Owner to VC's DID

  • To be capable of adding/removing VC's proofs or removing VC, one of your DIDs that you control has to be a DID Owner to VC's DID or role should exist that has with WRITE permission and assigned to both VC's DID and to Identity Wallet's DID that you control

Example request - Verifiable Credential JSON-LD

{
"resolver": "string",
"claims": [
{
"jsonld": {
"@context": [
"string"
],
"id": "string",
"type": [
"string"
],
"credentialSubject": {
"id": "string",
"name": "string"
},
"issuer": "string",
"issuanceDate": "string",
"expirationDate": "string",
"proof": {
"type": "string",
"creator": "string",
"created": "string",
"nonce": "string",
"domain": "string",
"signatureValue": "string"
}
},
"isPublicAccess": true,
"roles": [
"string"
]
}
],
"isPublicAccess": true,
"roles": [
"string"
]
}

Example request - Verifiable Credential JWT

{
"resolver": "string",
"claims": [
{
"jwt": "string"
}
],
"isPublicAccess": true,
"roles": [
"string"
]
}

Responses

Status

Meaning

Description

Schema

200

OK

VCs successfully stored

Inline

403

Forbidden

Missing access rights

Inline

422

Unprocessable Entity

Missing required params

Inline

500

Internal Server Error

Configure wallet failed

Inline

Response schema

Status code - 200

Name

Type

Description

Optional

resolver

String

DID resolver type that was used

no

vcs

Array

Verifiable Credentials that were stored

no

Status code - 403/422/500

Name

Type

Description

Optional

statusCode

Number

HTTP status code

no

errorType

String

Error type

no

errorMessage

String

Error message

no

Patch Verifiable Credentials with new Proofs

Patch /claims

Headers

Field

Description

Required

Authorization

Base Auth Token

yes

x-did-auth

DID Auth Token

yes

Content-Type

application/json

yes

Request parameters

Field

Description

Type

Optional

resolver

DID resolver type. Defaults to UniResolverSpherity if not provided.

String

yes

vcs

Verifiable Credentials

Array

no

Example request - Extending (patching) Verifiable Credential with new proof

{
"resolver": "string",
"claims": [
{
"jsonld": {
"@context": [
"string"
],
"id": "string",
"type": [
"string"
],
"credentialSubject": {
"id": "string",
"name": "string"
},
"issuer": "string",
"issuanceDate": "string",
"expirationDate": "string",
"proof": {
"type": "string",
"creator": "string",
"created": "string",
"nonce": "string",
"domain": "string",
"signatureValue": "string"
}
}
}
]
}

Responses

Status

Meaning

Description

Schema

200

OK

VCs successfully patched

Inline

403

Forbidden

Missing access rights

Inline

422

Unprocessable Entity

Missing required params

Inline

500

Internal Server Error

Configure wallet failed

Inline

Response schema

Status code - 200

Name

Type

Description

Optional

resolver

String

DID resolver type that is used

no

vcs

Array

Verifiable Credentials that were patched with another proof

no

Status code - 422/500

Name

Type

Description

Optional

statusCode

Number

HTTP status code

no

errorType

String

Error type

no

errorMessage

String

Error message

no

Verify Verifiable Credentials

Patch /claims

Headers

Field

Description

Required

Authorization

Base Auth Token

yes

x-did-auth

DID Auth Token

yes

Content-Type

application/json

yes

Request parameters

Field

Description

Type

Optional

resolver

DID resolver type. Defaults to UniResolverSpherity if not provided.

String

yes

vcs

Verifiable Credentials to be verified

Array

no

Example request - Verifying Verifiable Credential JSON-LD

{
"resolver": "string",
"claims": [
{
"jsonld": {
"@context": [
"string"
],
"id": "string",
"type": [
"string"
],
"credentialSubject": {
"id": "string",
"name": "string"
},
"issuer": "string",
"issuanceDate": "string",
"expirationDate": "string",
"proof": {
"type": "string",
"creator": "string",
"created": "string",
"nonce": "string",
"domain": "string",
"signatureValue": "string"
}
}
}
]
}

Example request = Verifying Verifiable Credential JWT

const body = {
"resolver": "UniResolverSpherity",
"claims": [
{
"jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NkstUiJ9.eyJqdGkiOiJkaWQ6c3BoZXJpdHk6MHhhZjRjOGU4NGQzMDBmOWU0YTc1NmM0M2VmMTJhMjUyMjQ0MGM3NDI4IiwiaXNzIjoiZGlkOnNwaGVyaXR5OjB4MmEzNDVlNzYxYzQ1MTkzMTNkZjBlMGZiOWFmOWFlNjEwY2E3ZDE0MCIsInN1YiI6ImRpZDpzcGhlcml0eToweDJhMzQ1ZTc2MWM0NTE5MzEzZGYwZTBmYjlhZjlhZTYxMGNhN2QxNDAiLCJ2YyI6eyJAY29udGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy92MSJdLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIl0sImNyZWRlbnRpYWxTdWJqZWN0Ijp7Im5hbWUiOiJBbGV4In19LCJpYXQiOjE1Njg5NTgzNjcsImV4cCI6MTY1NTM1ODM2N30.8Bf5yEbxF1GnuYp45qUmbRjM-xdcEmyVmbkXIxCA9UtJb7cPeKLGgNn6ZM_DAnS2q1BtLqKdtebuMpBtoKkkigA"
}
]
}

Responses

Status

Meaning

Description

Schema

200

OK

VCs successfully verified

Inline

422

Unprocessable Entity

Missing required params

Inline

500

Internal Server Error

Configure wallet failed

Inline

Response Schema

Status code - 200

Name

Type

Description

Optional

resolver

String

DID resolver type that was used

no

vcs

Array

Verifiable Credentials that were verified

no

Status code - 422/500

Name

Type

Description

Optional

statusCode

Number

HTTP status code

no

errorType

String

Error type

no

errorMessage

String

Error message

no

Delete Verifiable Credentials

DELETE /claims

Headers

Field

Description

Required

Authorization

Access Token JWT

yes

Content-Type

application/json

yes

Request parameters

Field

Description

Type

Optional

resolver

DID resolver type. Defaults to UniResolverSpherity if not provided.

String

no

ids

Identifiers of stored VCs. It can be identified using _id field inside response from Fecth/Store requests

Array

yes

Example request

{
"resolver": "InterlinkedQuorum",
"ids": [
"5d4cd994fb6ae51c5c87b1a6",
"5d4cda87fb6ae55b6287b1a9"
]
}

ids can be identified using the _id field inside a response from Fetch/Store requests.

Verifiable credentials (VC) can only be removed by the owner of the decentralized identifier (DID), except in the following cases:

  • VC has no DID - VC has no id field or id is not a valid DID but just some URI

  • VC DID owns itself - For example, VC has id field value that equals to DID owner value from it's DID document

Responses

Status

Meaning

Description

Schema

200

OK

VCs deleted successfully

Inline

403

Forbidden

Missing access rights

Inline

422

Unprocessable Entity

Missing required params

Inline

500

Internal Server Error

Configure wallet failed

Inline

Response Schema

Status code - 200

Name

Type

Description

Optional

resolver

String

DID resolver type that was used

no

vcs

Array

Verifiable Credentials that were deleted

no

Status code - 403/422/500

Name

Type

Description

Optional

statusCode

Number

HTTP status code

no

errorType

String

Error type

no

errorMessage

String

Error message

no