Endpoints

Create Identity Vault

In case of ECS Vault, the first Identity Wallet gets generated automatically, so that Identity Wallet's details can be spotted in the response

In case of MPC Vault, the first Identity Wallet is not generated automatically, the process requires Identity Vault initialization and calling Create Identity Vault's Wallet separately (can be found below)

In case of Vault with BIP44 hierarchy, mnemonic will be returned to user only once - at the time when the first Identity Wallet is generated

POST /vaults

Headers

Field

Description

Required

Authorization

Base Auth Token

yes

Content-Type

application/json

yes

Request parameters

Parameter

Description

Type

Required

Default

name

Identity Vault's name

String

yes

-

description

Identity Vault's description

String

no

""

parentID

Identity Vault's parent Id

String

no

-

hierarchy

Identity Vault's hierarchy

String

no

"NONE"

keyManagement

Identity Vault's key management

String

no

"ECS"

walletConfig

Config template for Identity Wallet(s)

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

-

mpcAccountID

MPC Account Id

String

yes (MPC only)

-

mpcGroups

Quorum Policy for controlling Identity Wallet(s) of a particular Identity Vault using MPC

Object

yes (MPC only)

-

name

MPC group name

String

yes (MPC only)

-

requiredApprovals

Number of required approvals

Number

yes (MPC only)

-

members

MPC group members

Array

yes (MPC only)

-

id

MPC group member Id

String

yes (MPC only)

-

mpcAccountID

Identity Vault's MPC account Id

String

yes (MPC only)

-

mpcVaultID

Identity Vault's MPC vault Id

String

yes (MPC only)

-

Example request - ECS Vault, BIP44 Hierarchy, DID document update

{
"name": "string",
"description": "string",
"parentID": "string",
"hierarchy": "BIP44",
"keyManagement": "ECS",
"walletConfig": {
"didMethod": "spherity",
"apiUrl": "string"
"txsInput": [
{
"service": {
"name": "string",
"value": "string",
"validity": 0
}
},
{
"delegate":{
"address": "string",
"validity": 0
}
},
{
"newOwner": "string"
}
]
}
}

Example request - MPC Vault, BIP44 Hierarchy, no DID document update

{
"name": "string",
"description": "string",
"parentID": "string",
"hierarchy": "BIP44",
"keyManagement": "MPC",
"mpcAccountID": "string",
"mpcGroups": [
{
"name": "string",
"requiredApprovals": 0,
"members": [
{
"id": "string"
}
]
}
]
}

Responses

Status

Meaning

Description

Schema

200

Created

New identity vault created successfully

Inline

422

Missing params

Missing required params or invalid params

Inline

500

Internal Server Error

Create identity vault failed

Inline

Response Schema

Status code 200

Name

Description

Type

Optional

vault

Created Identity Vault

Object

no

id

Identity Vault Id

String

no

name

Identity Vault name

String

no

description

Identity Vault description

String

no

parentID

Identity Vault parent Id

String

yes (if provided at creation)

hierarchy

Identity Vault hierarchy

String

no

mnemonic

Identity Vault's mnemonic (encrypted)

String

yes (ECS + BIP44 only)

keyManagement

Identity Vault key management

String

no

status

Identity Vault status

String

no

walletConfig

Config template for Identity Wallet(s)

Object

no

didMethod

Identity Wallet DID method

String

yes (if provided at creation)

apiUrl

API host for DID document update

String

yes (if provided at creation)

txsInput

Details for DID document update

Array

yes (if provided at creation)

service

DID document service

Object

yes (if provided at creation)

name

Service name

String

yes (if provided at creation)

value

Service value i.e. URL

String

yes (if provided at creation)

validity

Service validity offset in ms

Number

yes (if provided at creation)

delegate

DID document delegate

Object

yes (if provided at creation)

address

Delegate address i.e. Ethereum address

String

yes (if provided at creation)

validity

Delegate validity offset in ms

Number

yes (if provided at creation)

newOwner

New DID owner address i.e. Ethereum address

String

yes (if provided at creation)

wallets

Identity Wallets

Array

no

vaultId

Identity Vault Id

String

no

isHDWallet

Is BIP44 or a plain key-pair

Boolean

no

index

Identity Wallet's index

Number

yes (BIP44 Vault only)

privateKeyHex

Identity Wallet's private key HEX (encrypted)

String

yes (ECS Vault only)

publicKeyDER

Identity Wallet's public key DER-encoded

String

yes (MPC Vault only)

ethereumAddress

Identity Wallet's ethereum address

String

no

didMethod

Identity Wallet's DID method

String

no

did

Identity Wallet's DID

String

no

alias

Identity Wallet's human-readable alias

String

no

created

Identity Wallet's creation date

String

no

_id

Identity Wallet's id

String

no

mpcAccountID

Identity Vault's MPC account Id

String

yes (MPC Vault only)

mpcVault

body

Object

yes (MPC Vault only)

id

body

String

yes (MPC Vault only)

Example response (200) - ECS Vault, BIP44 Hierarchy, DID document update

{
"vault": {
"id": "string",
"name": "string",
"description": "string",
"parentID": "string",
"hierarchy": "BIP44",
"keyManagement": "ECS",
"status": "INITIALIZED",
"walletConfig": {
"didMethod": "spherity",
"apiUrl": "string",
"txsInput": [
{
"newOwner": "string"
},
{
"delegate": {
"validity": 0
}
},
{
"service":{
"name": "string",
"value": "string",
"validity": 0
}
}
]
},
"wallets": [
{
"vaultId": "string",
"isHDWallet": false,
"_id": "string",
"index": 0,
"publicKeyHex": "string",
"ethereumAddress": "string",
"didMethod": "spherity",
"did": "string",
"alias": "string",
"created": "string",
}
]
}
}

Example response (200) - MPC Vault, BIP44 Hierarchy, no DID document update

{
"vault": {
"id":" string",
"name": "string",
"description": "string",
"parentID": "string",
"hierarchy": "BIP44",
"keyManagement": "MPC",
"status": "NOT_INITIALIZED",
"walletConfig": {
"didMethod": "spherity"
},
"wallets": [],
"mpcVault": {
"id": "string"
},
"mpcAccountID": "srting"
}
}

Status code 422/500

Field

Description

Type

Optional

statusCode

HTTP status code

Number

no

errorType

Error type

String

no

errorMessage

Error message

String

no

Create Identity Vault's Wallet

Applicable for: ECS Vaults with BIP44 Hierarchy, any MPC Vaults

  • ECS Vaults with BIP44 Hierarchy:

    • Derives identity wallet for the next index of HD Wallet

    • Updates DID document (if wallet config provided):

      • By default it looks for walletConfig from vault details

      • walletConfig extension/override can be provided inside of request body

  • MPC Vaults:

    • Generates first identity wallet or derives one for the next index of HD Wallet

POST /vaults/:vaultID/wallet

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

Default

vaultID

Parent Identity Vault Id

String

yes

-

wallet

Identity Wallet details to be stored

Object

no

-

alias

Human-readable alias for DID

String

no

DID value

walletConfig

Config template for Identity Wallet(s)

Object

no

taken from vault's wallet config if exist

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 milliseconds from the current date

Number

no

-

delegate

DID document 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

Delegate validity. Offset in milliseconds from the current date

Number

no

-

newOwner

DID of a new owner

String

no

-

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

Responses

Status

Meaning

Description

Schema

200

Created

New identity vault's wallet created successfully

Inline

403

Forbidden

JWT validation failed

Inline

409

Conflict

Identity vault is not in INITIALIZED status yet (MPC only)

Inline

422

Unprocessable Entity

Missing required params or invalid params

Inline

500

Internal Server Error

Create identity vault failed

Inline

Response Schema

Status code 200

Field

In

Description

Type

Optio

wallet

body

Generated Identity Wallet

Object

no

vaultId

body

Identity Vault Id

String

no

_id

body

Identity Wallet Id

String

no

index

body

Identity Wallet's index

Number

yes (BIP44 only)

publicKeyDER

body

Identity Wallet's public key DER-encoded

String

yes (MPC only)

publicKeyHex

body

Identity Wallet's public key HEX

String

no

ethereumAddress

body

Identity Wallet's ethereum address

String

no

didMethod

body

Identity Wallet's DID method

String

no

did

body

Identity Wallet's DID

String

no

alias

body

Identity Wallet's human-readable alias

String

no

created

body

Identity Wallet's creation date

String

no

Example response (200) - ECS Vault, BIP44

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

Example response (200) - MPC Vault, BIP44

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

Status code 403/409/422/500

Field

Description

Type

Optional

statusCode

HTTP status code

Number

no

errorType

Error type

String

no

errorMessage

Error message

String

no

Get Identity Vaults

You can fetching Identity Vaults by:

  1. Identity Vault id

  2. Identity Vaults parentID

    • Identity Vault's MPC account Id must be provided in case of fetching MPC Vaults

  3. Identity Vaults MPC account Id (MPC only)

  4. Identity Vaults MPC vault Id (MPC only)

GET /vaults

Headers

Field

Description

Required

Authorization

Base Auth Token

yes

Request parameters

Parameter

Description

Type

id

Identity Vault Id

String

parentID

Identity Vault's parent Id

String

mpcAccountID

Identity Vault's MPC account Id

String

mpcVaultID

Identity Vault's MPC vault Id

String

Responses

Status

Meaning

Description

Schema

200

Created

New identity vault's wallet created successfully

Inline

422

Unprocessable Entity

Missing required params or invalid params

Inline

500

Internal Server Error

Create identity vault failed

Inline

Response Schema

Status code 200

Field

Description

Type

Optional

body

Get Identity Vaults Response

Object

no

vaults

Identity Vaults

Array

no

id

Identity Vault Id

name

Identity Vault name

String

no

description

Identity Vault description

String

no

parentID

Identity Vault parent Id

String

yes

hierarchy

Identity Vault hierarchy

String

no

mnemonic

Identity Vault's mnemonic (encrypted)

String

yes (ECS + BIP44 only)

keyManagement

Identity Vault key management

String

no

status

Identity Vault status

String

no

walletConfig

Config template for Identity Wallet(s)

Object

no

didMethod

Identity Wallet DID method

String

no

apiUrl

API host for DID document update

String

yes

txsInput

Details for DID document update

Array

yes

service

DID document service

Object

yes

name

Service name

String

yes

value

Service value i.e. URL

String

yes

validity

Service validity offset in ms

Number

yes

delegate

DID document delegate

Object

yes

address

Delegate address i.e. Ethereum address

String

yes

validity

Delegate validity offset in ms

Number

yes

newOwner

New DID owner address i.e. Ethereum address

String

yes

wallets

Identity Wallets

Array

no

vaultId

Identity Vault Id

String

no

_id

Identity Wallet Id

String

no

index

Identity Wallet's index

Number

yes (BIP44 only)

privateKeyHex

Identity Wallet's private key HEX (encrypted)

String

yes (ECS only)

publicKeyDER

Identity Wallet's public key DER-encoded

String

yes (MPC only)

publicKeyHex

Identity Wallet's public key HEX

String

no

ethereumAddress

Identity Wallet's ethereum address

String

no

didMethod

Identity Wallet's DID method

String

no

did

Identity Wallet's DID

String

no

alias

Identity Wallet's human-readable alias

String

no

created

Identity Wallet's creation date

String

no

mpcAccountID

Identity Vault's MPC account Id

String

no (MPC only)

mpcVaultID

Identity Vault's MPC vault

Object

no (MPC only)

id

Identity Vault's MPC vault Id

String

no (MPC only)

Example response (200) - ECS Vault, BIP44 Hierarchy, Wallet Config

{
"vaults":[
{
"id": "string",
"name": "string",
"description": "string",
"parentID": "string",
"hierarchy":"BIP44",
"mnemonic": "string",
"keyManagement":"ECS",
"status":"INITIALIZED",
"walletConfig": {
"didMethod": "spherity",
"apiUrl": "string",
"txsInput": [
{
"delegate": {
"validity": 0
}
},
{
"service":{
"name": "string",
"value": "string",
"validity": 0
}
},
{
"newOwner": "string"
}
]
},
"wallets":[
{
"vaultId": "string",
"_id": "string",
"index": 0,
"privateKeyHex": "string",
"publicKeyHex": "string",
"ethereumAddress":"string",
"didMethod":"spherity",
"did": "string",
"alias": "string",
"created": "string"
}
]
}
]
}

Example response (200) - MPC Vault, BIP44 Hierarchy, Wallet Config

{
"vaults":[
{
"id": "string",
"name": "string",
"description": "string",
"parentID": "string",
"hierarchy":"BIP44",
"keyManagement":"MPC",
"status":"INITIALIZED",
"walletConfig": {
"didMethod": "spherity",
"apiUrl": "string",
"txsInput": [
{
"delegate": {
"validity": 0
}
},
{
"service":{
"name": "string",
"value": "string",
"validity": 0
}
},
{
"newOwner": "string"
}
]
},
"wallets":[
{
"vaultId": "string",
"_id": "string",
"index": 0,
"publicKeyDER": "string",
"publicKeyHex": "string",
"ethereumAddress":"string",
"didMethod":"spherity",
"did": "string",
"alias": "string",
"created": "string"
}
],
"mpcAccountID": "string",
"mpcVault": {
"id": "string"
}
}
]
}

Status code 422/500

Field

Description

Type

Optional

statusCode

HTTP status code

Number

no

errorType

Error type

String

no

errorMessage

Error message

String

no

Delete Identity Vault

DELETE /vaults

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

_id

Identity Vault Id

String

no

Example request

{
"_id":"5dafd5fc0388155dc839cdb1"
}

Responses

Status

Meaning

Description

Schema

200

Completed

Delete operations were completed

Inline

422

Unprocessable Entity

Missing required params or invalid params

Inline

500

Internal Server Error

Create identity vault failed

Inline

Response Schema

Status code 200

Name

Description

Type

Optional

wallets

List of removed wallets of a given vault

Array

no

errors

Array of errors for failed operations

Array

no

Example response (200) - Success

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

Example response (200) - Failure

{
"wallets": [],
"errors": [
{
"wallets": [
{
"vaultId": "string",
"publicKeyHex": "string",
"ethereumAddress": "string",
"didMethod": "spherity",
"did": "string",
"privateKeyHex": "string",
"alias": "string",
"created": "string",
"_id": "string",
}
],
"error": {}
}
]
}

Status code 422/500

Field

Description

Type

Optional

statusCode

HTTP status code

Number

no

errorType

Error type

String

no

errorMessage

Error message

String

no