Endpoints

Get Roles

GET /roles

Headers

Field

Description

Required

Authorization

Base Auth Token

yes

x-did-auth

DID Auth Token

yes

Request parameters

Parameter

In

Description

Type

Default

permissions

query

Comma-separated list of permission types

String

-

Responses

Status

Meaning

Description

Schema

200

OK

OK

Inline

403

Forbidden

Missing access rights

Inline

500

Internal Server Error

Get role(s) failed

Inline

Response schema

Status code - 200

Name

Type

Description

Optional

roles

Array

Roles array

no

did

Object

Role DID

no

crteator

String

DID of a role creator

no

permissions

Array

Role permission types

no

description

String

Role description

no

createdAt

Number

Role creation date time as Unix timestamp in ms

no

updatedAt

Number

Role update date time as Unix timestamp in ms

no

_id

String

Identity wallet's db Id

no

Example response (200)

{
"roles": [
{
"_id": "5dcce4ca8d6f970109b26255",
"did": "did:spherity:0xd521b6de277c22ae5acdc75f8717ccea26992bca",
"creator": "did:spherity:0x40f2b321b3b78c3cf78f449203de921268e8ac2a",
"permissions": [
"Read",
"Write"
],
"description": "R1",
"createdAt": 1573709002134,
"updatedAt": 1573709002134
}
]
}

Status code - 403/500

Name

Type

Description

Optional

statusCode

Number

HTTP status code

no

errorType

String

Error type

no

errorMessage

String

Error message

no

Create Role

POST /roles

Headers

Field

Description

Required

Authorization

Base Auth Token

yes

x-did-auth

DID Auth Token

yes

Content-Type

application/json

yes

Request parameters

Field

In

Description

Type

Required

Default

description

body

Role description

String

no

""

permissions

body

Role permissions

Array

no

-

wallet

body

Role's Identity Wallet details to be stored

Object

no

-

alias

body

Human-readable alias for Role DID

String

no

DID value

walletConfig

body

Identity Wallet config

Object

no

-

didMethod

body

DID method to be used

String

no

"spherity"

apiUrl

body

API host to be used for the DID doc update

String

no

self host

txsInput

body

Details for DID doc update

Object

no

-

newOwner

body

DID of a new owner

String

no

-

Example request

{
"description": "string",
"permissions": [
"string"
],
"wallet": {
"alias": "string"
},
"walletConfig": {
"didMethod": "spherity",
"apiUrl": "string",
"txsInput": [
{
"newOwner": "string",
}
]
}
}

Responses

Status

Meaning

Description

Schema

200

Created

OK

Inline

403

Forbidden

Missing access rights

Inline

500

Internal Server Error

Create wallet failed

Inline

Response schema

Status code - 200

Name

Type

Description

Optional

role

Object

Role data

no

did

Object

Role DID

no

crteator

String

DID of a role creator

no

permissions

Array

Role permission types

no

description

String

Role description

no

createdAt

Number

Role creation date time as Unix timestamp in ms

no

updatedAt

Number

Role update date time as Unix timestamp in ms

no

_id

String

Identity wallet's db Id

no

Example response (200)

{
"role": {
"did": "did:spherity:0xf28bf507a573b807d0f02b2cbaf9188e2714ed03",
"creator": "did:spherity:0x40f2b321b3b78c3cf78f449203de921268e8ac2a",
"permissions": [
"Read",
"Write"
],
"description": "R11",
"createdAt": 1574057458978,
"updatedAt": 1574057458978,
"_id": "5dd235f21ac7ebfbe81b76b9"
}
}

Status code - 403/500

Name

Type

Description

Optional

statusCode

Number

HTTP status code

no

errorType

String

Error type

no

errorMessage

String

Error message

no

Update Roles

PUT /roles

Headers

Field

Description

Required

Authorization

Base Auth Token

yes

x-did-auth

DID Auth Token

yes

Content-Type

application/json

yes

Request parameters

Field

In

Description

Type

Required

Default

description

body

Role description

String

no

""

permissions

body

Role permissions

Array

no

-

wallet

body

Role's Identity Wallet details to be stored

Object

no

-

alias

body

Human-readable alias for Role DID

String

no

DID value

walletConfig

body

Identity Wallet config

Object

no

-

didMethod

body

DID method to be used

String

no

"spherity"

apiUrl

body

API host to be used for the DID doc update

String

no

self host

txsInput

body

Details for DID doc update

Object

no

-

newOwner

body

DID of a new owner

String

no

-

Example request

{
"description": "string",
"permissions": [
"string"
],
"wallet": {
"alias": "string"
},
"walletConfig": {
"didMethod": "spherity",
"apiUrl": "string",
"txsInput": [
{
"newOwner": "string",
}
]
}
}

Responses

Status

Meaning

Description

Schema

200

Created

OK

Inline

403

Forbidden

Missing access rights

Inline

422

Unprocessable Entity

Missing required parameter

Inline

500

Internal Server Error

Create wallet failed

Inline

Response schema

Status code - 200

Name

Type

Description

Optional

roles

Array

Updated roles

no

_id

String

Role id

no

did

Object

Role DID

no

crteator

String

DID of a role creator

no

permissions

Array

Role permission types

no

description

String

Role description

no

createdAt

Number

Role creation date time as Unix timestamp in ms

no

updatedAt

Number

Role update date time as Unix timestamp in ms

no

errors

Array

Failed update operations

yes

roleDid

String

Role DID

yes

message

String

Error message

yes

Example response (200) - success

{
"roles": [
{
"_id": "5dcce4ca8d6f970109b26255",
"did": "did:spherity:0xd521b6de277c22ae5acdc75f8717ccea26992bca",
"creator": "did:spherity:0x40f2b321b3b78c3cf78f449203de921268e8ac2a",
"permissions": [
"Read"
],
"description": "R111",
"createdAt": 1573709002134,
"updatedAt": 1574060088740
}
],
"errors": []
}

Example response (200) - failure

{
"roles": [],
"errors": [
{
"roleDid": "string",
"message": "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

Delete Roles

DELETE /roles

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

dids

Comma-separated list of role DIDs

String

no

Example request

{
"ids":"string"
}

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

Type

Description

Optional

roles

Array

Deleted roles

no

_id

String

Role id

no

did

Object

Role DID

no

crteator

String

DID of a role creator

no

permissions

Array

Role permission types

no

description

String

Role description

no

createdAt

Number

Role creation date time as Unix timestamp in ms

no

updatedAt

Number

Role update date time as Unix timestamp in ms

no

errors

Array

Failed update operations

yes

roleDid

String

Role DID

yes

message

String

Error message

yes

Example response (200) - Success

{
"roles": [
{
"_id": "5dcce4ca8d6f970109b26255",
"did": "did:spherity:0xd521b6de277c22ae5acdc75f8717ccea26992bca",
"creator": "did:spherity:0x40f2b321b3b78c3cf78f449203de921268e8ac2a",
"permissions": [
"Read"
],
"description": "R111",
"createdAt": 1573709002134,
"updatedAt": 1574060088740
}
],
"errors": []
}

Example response (200) - Failure

{
"roles": [],
"errors": [
{
"roleDid": "string",
"message": "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

Create Role Assignments

POST /roles/assignmnets

Headers

Field

Description

Required

Authorization

Base Auth Token

yes

x-did-auth

DID Auth Token

yes

Content-Type

application/json

yes

Delete Role Assignments

DELETE /roles/assignmnets

Headers

Field

Description

Required

Authorization

Access Token JWT

yes

Content-Type

application/json

yes