Endpoints

Create and retrieve identities

Get Identity Wallets

You can fetch wallets by:

  1. Identity Vault Id

  2. Identity Wallet DID

  3. Identity Wallet Alias

  4. Without any query parameters to fetch all wallets

GET /wallets

Headers

Field

Description

Required

Authorization

Base Auth Token

yes

Request parameters

Parameter

Description

Type

vaultId

Identity Vault Id

String

did

Identity Wallet's DID

String

alias

Identity Wallet's Alias

String

Responses

Status

Meaning

Description

Schema

200

OK

OK

Inline

500

Internal Server Error

Get wallet(s) failed

Inline

Response schema

Status code - 200

Name

Type

Description

Optional

wallets

Array

Identity Wallets

no

vaultId

String

Parent Identity Vault Id

yes

isHDWallet

Boolean

Is it HD Wallet (BIP44) or a plain key-pair

no

index

Number

Index of a wallet from HD Wallet

yes (BIP44 Vault only)

publicKeyDER

String

Public key DER-encoded

yes (MPC Vault only)

publicKeyHex

String

Public key HEX

no

ethereumAddress

String

Ethereum address

no

did

Object

DID

no

didMethod

String

DID method

no

alias

String

Human-readable alias for DID

no

created

String

Creation date

no

_id

String

Identity wallet's db Id

no

Example response (200)

{
"wallets": [
{
"alias": "string",
"vaultId": "string",
"isHDWallet": false,
"publicKeyDER": "string",
"publicKeyHex": "string",
"ethereumAddress":"string",
"did": "string",
"didMethod": "spherity",
"alias": "string",
"created": "string",
"_id": "string"
}
]
}

Status code - 500

Name

Type

Description

Optional

statusCode

Number

HTTP status code

no

errorType

String

Error type

no

errorMessage

String

Error message

no

Generate Identity Wallet

POST /wallet

Headers

Field

Description

Required

Authorization

Base Auth Token

yes

Content-Type

application/json

yes

Request parameters

Field

Description

Type

Required

Default

wallet

Identity Wallet details to be stored

Object

no

-

alias

Human-readable alias for DID

String

no

DID value

walletConfig

Identity Wallet config

Object

no

-

didMethod

DID method to be used

String

no

"spherity"

apiUrl

API host to be used for the DID doc update

String

no

self host

txsInput

Details for DID doc update

Object

no

-

newOwner

DID of a new owner

String

no

-

service

Input for DID doc service

String

no

-

name

Service name

String

no

-

value

Service URL

String

no

-

validity

Offset in milliseconds from the current date

Number

no

-

delegate

Input for DID doc delegate

Object

no

-

address

Ethereum address of a signing key delegate . Key-pair gets generated automatically if only validity was provided for delegate

String

no

-

validity

Offset in milliseconds from the current date

Number

no

-

Example request - ECS, config for New DID Owner, Service Endpoint & Signing Key Delegate

{
"wallet": {
"alias": "string",
},
"walletConfig": {
"didMethod": "spherity",
"apiUrl": "string",
"txsInput": [
{
"newOwner": "string",
},
{
"service":{
"name": "string",
"value": "string",
"validity": 0
}
},
{
"delegate":{
"validity": 0
}
}
]
}
}

Responses

Status

Meaning

Description

Schema

200

Created

OK

Inline

500

Internal Server Error

Create wallet failed

Inline

Response schema

Status code - 200

Name

Type

Description

Optional

wallet

Object

Created Identity Wallet

no

publicKeyHex

String

Public key HEX

no

ethereumAddress

String

ethereum address

no

did

Object

DID

no

didMethod

String

DID method

no

alias

String

Human-readable alias for DID

no

created

String

Creation date

no

_id

String

Identity wallet's db Id

no

Example response (200) - ECS, Configure Agent, and Delegate

{
"wallet":{
"publicKeyHex": "string",
"ethereumAddress": "string",
"did": "string",
"didMethod": "spherity",
"alias": "string",
"created": "string",
"_id": "string"
}
}

Status code - 500

Name

Type

Description

Optional

statusCode

Number

HTTP status code

no

errorType

String

Error type

no

errorMessage

String

Error message

no

Configure Identity Wallet

POST /wallet/configure

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

Default

wallet

Identity Wallet data

Object

yes

-

did

Identity Wallet DID

String

yes

-

walletConfig

Identity Wallet config

Object

yes

taken from vault's wallet config if exist

didMethod

DID method

String

no

taken from vault's wallet config if exist or "spherity"

apiUrl

API host for DID doc update

String

no

taken from vault's wallet config if exist or self host

txsInput

Details for DID doc update

Object

no

taken from vault's wallet config if exist

newOwner

DID of a new owner

String

no

taken from vault's wallet config if exist

service

Input for DID doc service

String

no

taken from vault's wallet config if exist

name

Service endpoint name

String

no

taken from vault's wallet config if exist

value

Service endpoint URL

String

no

taken from vault's wallet config if exist

validity

Offset in milliseconds from the current date

Number

no

taken from vault's wallet config if exist

delegate

Input for DID doc delegate

Object

no

taken from vault's wallet config if exist

address

Ethereum address of a signing key delegate . Key-pair gets generated automatically if only validity was provided for delegate

String

No

taken from vault's wallet config if exist

validity

Offset in milliseconds from the current date

Number

no

taken from vault's wallet config if exist

Body example - ECS, no config for Agent & Delegate

{
"wallet": {
"did": "string"
},
"walletConfig": {
"didMethod": "spherity",
"apiUrl": "string",
"txsInput": [
{
"newOwner": "string"
},
{
"service": {
"name": "string",
"value": "string",
"validity": 0
}
},
{
"delegate":{
"validity": 0
}
}
]
}
}

Responses

Status

Meaning

Description

Schema

200

Configured

DID document successfully updated

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

wallet

Object

Created Identity Wallet

no

isHDWallet

Boolean

Is it HD Wallet (BIP44) or a plain key-pair

no

index

Number

Index of a wallet from HD Wallet

yes (BIP44 Vault only)

publicKeyDER

String

Public key DER-encoded

yes (MPC Vault only)

publicKeyHex

String

Public key HEX

no

ethereumAddress

String

Ethereum address

no

did

Object

DID

no

didMethod

String

DID method

no

alias

String

Human-readable alias for DID

no

created

String

Creation date

no

_id

String

Identity wallet's db Id

no

Example response (200) - ECS, configure new DID Owner, Service Endpoint & Signing Key Delegate

{
"wallet": {
"vaultId": "string",
"isHDWallet": false,
"publicKeyDER": "string",
"publicKeyHex": "string",
"ethereumAddress": "string",
"did": "string",
"didMethod": "spherity",
"alias": "string",
"created": "string",
"_id":"string"
}
}

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

Rename Identity Wallet

POST /wallet/rename

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

Default

wallets

List of did/alias pairs to be renamed

Array

yes

-

did

DID

String

yes

-

alias

New human-readable alias for DID

String

yes

-

Example request - ECS, no config for Agent & Delegate

{
"wallets": [
{
"did": "string",
"alias": "string"
}
]
}

Responses

Status

Meaning

Description

Schema

200

Completed

Renaming operation(s) completed

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

wallets

Array

List of wallets with new aliases

no

alias

String

New human-readable alias for DID

no

vaultId

String

Vault Id that holds Identity Wallet

yes (Vault generated only)

isHDWallet

Boolean

Is it HD Wallet (BIP44) or a plain key-pair

no

index

Number

Index of a wallet from HD Wallet

yes (BIP44 Vault only)

publicKeyDER

String

Public key DER-encoded

yes (MPC Vault only)

publicKeyHex

String

Public key HEX

no

ethereumAddress

String

Ethereum address

no

did

Object

DID

no

didMethod

String

DID method

no

alias

String

Human-readable alias for DID

no

created

String

Creation date

no

_id

String

Identity wallet's db Id

no

errors

Array

Array of errors for failed operations

no

wallet

String

Affected wallet

no

did

String

DID

no

alias

String

Alias

no

error

Object

Error object

no

Example response (200) - Success

{
"wallets": [
{
"alias": "string",
"vaultId": "string",
"isHDWallet": false,
"publicKeyDER": "string",
"publicKeyHex": "string",
"ethereumAddress":"string",
"did": "string",
"didMethod": "spherity",
"alias": "string",
"created": "string",
"_id": "string"
}
]
}

Response example (200) - Failure

{
"wallets": [],
"errors": [
"wallet": {
"did": "string",
"alias": "string"
},
"error": {}
]
}

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

Delete Identity Wallet

DELETE /wallet

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

Default

ids

The Ids of the Identity Wallets to delete

Array

yes

-

Example request - ECS, no config for Agent & Delegate

{
"ids":[
"5daff27ca96d7d85666d828c"
]
}

Responses

Status

Meaning

Description

Schema

200

Completed

Deletion operation(s) completed

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

ids

Array

List of removed DIDs

no

errors

Array

Array of errors for failed operations

no

did

String

DID that was not removed

no

error

String

Error object

no

Example response (200) - Success

{
"ids": [
"string"
]
}

Example response (200) - Failure

{
"ids": [],
"errors":[
{
"did": "string",
"error": {}
}
]
}

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