Attributes API

Created by

Remus Golgot

Last updated Feb 18, 2019

ATTRIBUTES

List Attribute Types

Endpoint

GET /api/attributes/types/list

Response

{ 
  success: true,  
  attribute_types: [ {  
    id: 1,  
    name: 'first_name',  
    data_type: 'text',  
    validation: '{"required": true, "minLength": 2, "maxLength": 80}',  
    options: '{"documentRequired":true}' 
  },  
  { ...}  
  ],  
  count: 12  
}

Get Attribute Type

Endpoint

GET /api/attributes/types

Query Parameters

Name Type Description Required
name string The name of the attribute type

Response

{  
  success: true,  
  attribute_type: {  
    id: 1,  
    name: 'first_name',  
    data_type: 'text',  
    validation: '{"required": true, "minLength": 2, "maxLength": 80}',  
    options: '{"documentRequired":true}'  
  }  
}

Errors

Message Reason
Message Reason
'Missing required property: name' The 'name' query parameter is missing from the request
'Attribute type not found' An incorrect value was provided for the 'name' query parameter

Create Attribute

Endpoint

POST /api/attributes

Body Parameters

Name Type Description Required
secret string The secret of the sender
publicKey string The publicKey of the sender
asset object The request asset
attribute object
type string The type of the attribute that will be created
owner string The Persona address for which the attribute will be created
value string The attribute value (encrypted with the owner's public key)
associations array The attribute associations for the new attribute
expire_timestamp integer The expiration timestamp of the attribute

Request

{
  "secret":"secret",  
  "publicKey":"025025025025025025025025025025025025025025025025025025025025025025",  
  "asset":{
     "attribute":[{
        "type":"first_name",
        "owner":"LMs6hQAcRYmQk4vGHgE2PndcXWZxc2Du3w",
        "value":"ABC",
        "associations":[1]
     }]
  }
}

Response

{
  "success":true,
  "transactionId":"b25f92a95e714d0d9f77ce5f5797ad1a166c265002f6d26596ee059bc1cb5597"
}

Errors

Message Reason
Message Reason
'Expire timestamp is required for this attribute type' Missing expire_timestamp for a type that requires it
'Expire timestamp must be a timestamp in the future' Expire_timestamp value is in the past, for a type that requires it
'Attribute type not found' An incorrect value was provided for the 'type' body parameter
'If associations are specified, they must be provided' An empty array ([]) was provided as the association value
'Associations are not supported for non-file attribute types' A non-file attribute does not accept associations during its creation  it cannot be underlying evidence for the value of any other attribute
'Incorrect association provided : one or more of the attributes to be associated Some of the attributes specified in the associations array belong to a different owner that the base attribute
does not exist or does not belong to the current owner'

Update Attribute

Endpoint

PUT /api/attributes

Body Parameters

Name Type Description Required
secret string The secret of the sender
publicKey string The publicKey of the sender
asset object The request asset
attribute object
type string The type of the attribute that will be created
owner string The Persona address for which the attribute will be created
value string The attribute value (encrypted with the owner's public key)
associations array The attribute associations for the new attribute
expire_timestamp integer The expiration timestamp of the attribute

Request

{
  "secret": "secret",
  "publicKey": "025025025025025025025025025025025025025025025025025025025025025025",
  "asset": {
    "attribute": [
      {
        "attributeId": 55,
        "type": "first_name",
        "owner": "LMs6hQAcRYmQk4vGHgE2PndcXWZxc2Du3w",
        "value": "newValue_ABC",
        "associations": [
          51
        ]
      }
    ]
  }
}

Response

{ "success":true,
"transactionId":"aebc29f408125d31eddcb25668c61281fd453f8e69f07f7092064d7c95334dca"
}

Errors

Message Reason
'Expire timestamp is required for this attribute type' Missing expire_timestamp for a type that requires it
'Expire timestamp must be a timestamp in the future' Expire_timestamp value is in the past, for a type that requires it
'Attribute type not found' An incorrect value was provided for the 'type' body parameter
'If associations are specified, they must be provided' An empty array ([]) was provided as the association value
'Incorrect association provided : The base attribute must be of data type file' A non-file attribute cannot accept associations during its update it cannot be underlying evidence for the value of any other attribute
'Incorrect association provided : one or more of the attributes to be associated Some of the attributes specified in the associations array belong to a different owner that the base attribute, or don't exist at all
does not exist or does not belong to the current owner'

Get Attribute Details

Endpoint

GET /api/attributes

Query Parameters

Name Type Description Required
owner string The Persona address for which attributes will be retrieved
type string The type of the attribute to be retrieved

Response

A. Query made by owner and type

{ "success":true,  
"attributes":[  
{

id: 27,

type: 'birthplace',

value: 'London',

owner: 'LMsaiMA7vf31LUoXMWcGvsMYQarphwN3Dg',

associations: null,

timestamp: 60076933,

expire_timestamp: null,

active: false,

yellowFlags: 0,

redFlags: 0,

rejected: false,

dangerOfRejection: false,

documented: false

}  
],  
"count":1  
}  

B. Query with no results

{ success: true, attributes: [], count: 0 }

Errors

Message Reason
'Missing required property: owner' The 'owner' query parameter is missing from the request

ATTRIBUTE VALIDATION REQUESTS

Create Validation Request

Endpoint

POST /api/attribute-validations/validationrequest

Body Parameters

Name Type Description Required
secret string The secret of the sender
publicKey string The publicKey of the sender
asset object The request asset
attribute object
type string The type of the attribute that will be created
owner string The Persona address for which the attribute will be created
validator string The Persona address of the validator

Request

{ secret: '...', publicKey: '...',  
asset: { validation: [{  
"type":"identity_card",  
"owner":"Lguu3RdVHxdBTsT3B5z6hHd9QsHN2UyZMk",  
"validator":"LNJJKBGmC1GZ89XbQ4nfRRwVCZiNig2H9M"  
}]  
}  
}

Response

{ "success":true,
"transactionId":"087810a8fe77e548679dcf11edada4e8521e1473fac7378c7736707a483303f6"
}

Errors

Message Reason
'Attribute not found' The provided attribute does not exist
'Owner cannot be the validator of his own attribute' The provided validator is the same as the attribute owner
'Owner address is invalid' The owner's address is invalid
'Validator address is invalid' The validator's address is invalid
'Validator already has a pending approval validation A validation request that is pending approval already exists for the attribute and validator
request for the given attribute'
'Validator already has a completed validation request for the given attribute' A validation request that is completed already exists for the attribute and validator
'Validator already has an in progress validation request for the given attribute' The validation request cannot be created since another request which is in progress already exists for the given attribute and validator
'Attribute has no associations and therefore cannot be validated' The provided attribute has no associations and a type that requires them
'Attribute is expired' The provided attribute is expired
'Attribute is rejected due to unsuccessful notarizations. The attribute was already rejected 3 times in a row ( or failed to gather 3 notarizations in a row during the first 7). The attribute must be updated, in order for the validation process to be resumed
Please update the attribute value and resume the notarization process'
'More than one attribute exists for this owner and type. The attribute referenced by <owner;type> cannot be uniquely determined (multiple attributes of the given type exist for the the given owner).
Please provide the attributeId instead of the type'
'Attribute is rejected due to unsuccessful notarizations. The provided attribute was rejected due to too many red flags ( unsuccessful notarizations ) or insufficient notarizations acquired in the first 7 validations
Please update the attribute value and resume the notarization process'

Get Validation Requests

Endpoint

GET /api/attribute-validations/validationrequest

Query Parameters

Name Type Description Required
Name Type Description Required
owner string The Persona address for which attributes will be retrieved
validator string The type of the attribute to be retrieved
attributeId integer The ID of the attribute for which validation requests will be retrieved

At least one of the parameters above must be provided

Response

A. Query made by validator and attributeId

{ success: true,
attribute_validation_requests: [{
owner: 'Lguu3RdVHxdBTsT3B5z6hHd9QsHN2UyZMk',
type: 'identity_card',
id: 1,
attribute_id: 5,
status: 'COMPLETED',
validator: 'LNJJKBGmC1GZ89XbQ4nfRRwVCZiNig2H9M',
validation_type: 'FACE_TO_FACE',
reason: null,
timestamp: 56937084,
last_update_timestamp: null
}],
count: 1
}

B. Query with no results

{"success":true, "attribute_validation_requests":[], "count":0 }

Errors

Message Reason
'Either the attribute id, the validation request validator or the attribute owner must be provided' Incorrect parameters were provided
'Object didn't pass validation for format address: ' Incorrect Persona address was provided for the validator parameter

Get Validation Score

Endpoint

GET /api/attribute-validations/validationscore

Query Parameters

Name Type Description Required
owner string The Persona address of the attribute for which the validation score will be retrieved
type string The type of the attribute for which the validation score will be retrieved

Response

{ success: true, attribute_validations: 2 }

Errors

Message Reason
'Object didn't pass validation for format address: ' An incorrect Persona address was provided for the owner parameter
'Attribute not found' No attribute was found for the given owner and type
'Missing required property: owner' The 'owner' query parameter is missing from the request
'Missing required property: type' The 'type' query parameter is missing from the request
'More than one attribute exists for this owner and type. The attribute referenced by <owner;type> cannot be uniquely determined (multiple attributes of the given type exist for the the given owner).
Please provide the attributeId instead of the type'

Get Attribute Credibility

Endpoint

GET /api/attribute-validations/credibility

Query Parameters

Name Type Description Required
attributeId integer The ID of the attribute for which the credibility/trust points will be retrieved
months integer The number of months which is the base of the credibility/trust points calculation

Response

{"success":true,"trust_points":1}

Errors

Message Reason
'Missing required property: months' The 'months' query parameter is missing from the request
'The "months" query parameter must be a positive integer' The provided value for the 'months' parameter is either 0 or a negative number
'Attribute not found' The attribute provided by 'attributeId' in the request does not exist in the system

Approve Validation Request

Endpoint

POST /api/attribute-validations/approve

Body Parameters

Name Type Description Required
secret string The secret of the sender
publicKey string The publicKey of the sender
asset object The request asset
validation object
type string The type of the attribute that will be created
owner string The Persona address for which the attribute will be created
validator string The Persona address of the validator

Request

{ secret: '...', publicKey: '...',  
asset: { validation: [{  
"type":"identity_card",  
"owner":"Lguu3RdVHxdBTsT3B5z6hHd9QsHN2UyZMk",  
"validator":"LNJJKBGmC1GZ89XbQ4nfRRwVCZiNig2H9M"  
}]  
}  
}

Response

{ "success":true, transactionId:
'd133c35adde2da6c21b585c53d62deeefe2ec329407a12d9d011e7fe792c9233' }

Errors

Message Reason
'Only the validator is allowed to perform this action on a validation request' The user that performs the approve action must be the validator of that request
'The specified attribute validation request must be pending approval The provided request must be in PENDING_APPROVAL status for the approve action to be performed
for the action to take place'
'There is no validation request for this action' The validation request to be approved does not exist
'More than one attribute exists for this owner and type. The attribute referenced by <owner;type> cannot be uniquely determined (multiple attributes of the given type exist for the the given owner).
Please provide the attributeId instead of the type'
'Attribute is rejected due to unsuccessful notarizations. The attribute was already rejected 3 times in a row ( or failed to gather 3 notarizations in a row during the first 7). The attribute must be updated, in order for the validation process to be resumed
Please update the attribute value and resume the notarization process'
'Attribute is rejected due to unsuccessful notarizations. The provided attribute was rejected due to too many red flags ( unsuccessful notarizations ) or insufficient notarizations acquired in the first 7 validations
Please update the attribute value and resume the notarization process'
'There is no validation request that is pending approval or in progress The approval action cannot be performed since there is no validation request in the required state of PENDING_APPROVAL
for this attribute'

Decline Validation Request

Endpoint

POST /api/attribute-validations/decline

Body Parameters

Name Type Description Required
secret string The secret of the sender
publicKey string The publicKey of the sender
asset object The request asset
validation object
type string The type of the attribute that will be created
owner string The Persona address for which the attribute will be created
validator string The Persona address of the validator
reason string The reason for declining the request (limited to 1024 characters)

Request

{ secret: '...', publicKey: '...',  
asset: { validation: [{  
"type":"identity_card",  
"owner":"Lguu3RdVHxdBTsT3B5z6hHd9QsHN2UyZMk",  
"validator":"LNJJKBGmC1GZ89XbQ4nfRRwVCZiNig2H9M",  
"reason":"some reason"  
}]  
}  
}

Response

{ "success":true, transactionId:
'9c7fa6d63cf3dcd7765787a43115998a30e0b2e511516b2aee6fcc52f1844726' }

Errors

Message Reason
'Only the validator is allowed to perform this action on a validation request' The user that performs the approve action must be the validator of that request
'The specified attribute validation request must be pending approval The provided request must be in PENDING_APPROVAL status for the approve action to be performed
for the action to take place'
'The reason for declining a request is limited to 1024 characters' The reason provided for the decline is longer than 1024 characters
'A reason must be specified when declining a validation request' No reason is provided for the decline
'More than one attribute exists for this owner and type. The attribute referenced by <owner;type> cannot be uniquely determined (multiple attributes of the given type exist for the the given owner).
Please provide the attributeId instead of the type'
'Attribute is rejected due to unsuccessful notarizations. The attribute was already rejected 3 times in a row ( or failed to gather 3 notarizations in a row during the first 7). The attribute must be updated, in order for the validation process to be resumed
Please update the attribute value and resume the notarization process'
'There is no validation request that is pending approval or in progress The decline action cannot be performed since there is no validation request in the required state of PENDING_APPROVAL
for this attribute'

Notarize Validation Request

Endpoint

POST /api/attribute-validations/notarize

Body Parameters

Name Type Description Required
secret string The secret of the sender
publicKey string The publicKey of the sender
asset object The request asset
validation object
type string The type of the attribute that will be created
owner string The Persona address for which the attribute will be created
validator string The Persona address of the validator

Request

{ secret: '...', publicKey: '...',  
asset: { validation: [{  
"type":"identity_card",  
"owner":"Lguu3RdVHxdBTsT3B5z6hHd9QsHN2UyZMk",  
"validator":"LNJJKBGmC1GZ89XbQ4nfRRwVCZiNig2H9M"  
}]  
}  
}

Response

{ "success":true, transactionId:
'd6c8ed59c126f4d03b5588469f1ceb40b0d99f0ae1e07f5a474f4b9a16fe28ee' }

Errors

Message Reason
'Only the validator is allowed to perform this action on a validation request' The user that performs the approve action must be the validator of that request
'The specified attribute validation request must be in progress The provided request must be in IN_PROGRESS status for the approve action to be performed
for the action to take place'
'There is no validation request that is pending approval or in progress The notarization action cannot be performed since there is no validation request in the required state of IN_PROGRESS
for this attribute'
'Attribute is rejected due to unsuccessful notarizations. The attribute was already rejected 3 times in a row ( or failed to gather 3 notarizations in a row during the first 7). The attribute must be updated, in order for the validation process to be resumed
Please update the attribute value and resume the notarization process'
'More than one attribute exists for this owner and type. The attribute referenced by <owner;type> cannot be uniquely determined (multiple attributes of the given type exist for the the given owner).
Please provide the attributeId instead of the type'

Reject Validation Request

Endpoint

POST /api/attribute-validations/reject

Body Parameters

Name Type Description Required
secret string The secret of the sender
publicKey string The publicKey of the sender
asset object The request asset
validation object
type string The type of the attribute
owner string The Persona address of the owner
validator string The Persona address of the validator
reason string The reason for rejecting the request (limited to 1024 characters)

Request

{ secret: '...', publicKey: '...',  
asset: { validation: [{  
"type":"identity_card",  
"owner":"Lguu3RdVHxdBTsT3B5z6hHd9QsHN2UyZMk",  
"validator":"LNJJKBGmC1GZ89XbQ4nfRRwVCZiNig2H9M",  
"reason":"some reason"  
}]  
}  
}

Response

{ "success":true, transactionId:
'f85b100fc27d13069ce3ba446d70ff1c9c305c1243ea688cb71297a552fcc0c4' }

Errors

Message Reason
'Only the validator is allowed to perform this action on a validation request' The user that performs the approve action must be the validator of that request
'The specified attribute validation request must be in progress The provided request must be in IN_PROGRESS status for the approve action to be performed
for the action to take place'
'The reason for rejecting a request is limited to 1024 characters' The reason provided for the reject is longer than 1024 characters
'A reason must be specified when rejecting a validation request' No reason is provided for the reject
'There is no validation request that is pending approval or in progress The rejection action cannot be performed since there is no validation request in the required state of IN_PROGRESS
for this attribute'
'More than one attribute exists for this owner and type. The attribute referenced by <owner;type> cannot be uniquely determined (multiple attributes of the given type exist for the the given owner)
Please provide the attributeId instead of the type'
'Attribute is rejected due to unsuccessful notarizations. The attribute was already rejected 3 times in a row ( or failed to gather 3 notarizations in a row during the first 7). The attribute must be updated, in order for the validation process to be resumed
Please update the attribute value and resume the notarization process'

Cancel Validation Request

Endpoint

POST /api/attribute-validations/cancel

Body Parameters

Name Type Description Required
secret string The secret of the sender
publicKey string The publicKey of the sender
asset object The request asset
validation object
type string The type of the request that will be created
owner string The Persona address for which the request will be created
validator string The Persona address of the validator

Request

{ secret: '...', publicKey: '...',  
asset: { validation: [{  
"type":"identity_card",  
"owner":"Lguu3RdVHxdBTsT3B5z6hHd9QsHN2UyZMk",  
"validator":"LNJJKBGmC1GZ89XbQ4nfRRwVCZiNig2H9M"  
}]  
}  
}

Response

{ "success":true, transactionId:
'59125e2c1bdb4c4132bc6eccb16c16d46355a3d75bc3d80dfe2ee3ec59f70519' }

Errors

Message Reason
'Only the owner is allowed to perform this action on a validation request' The user that performs the approve action must be the owner of that request
'The specified attribute validation request must be pending approval The provided request must be in PENDING_APPROVAL status for the approve action to be performed
for the action to take place'
'There is no validation request that is pending approval or in progress The cancellation action cannot be performed since there is no validation request in the required state of PENDING_APPROVAL
for this attribute'
'Attribute is rejected due to unsuccessful notarizations. The attribute was already rejected 3 times in a row ( or failed to gather 3 notarizations in a row during the first 7). The attribute must be updated, in order for the validation process to be resumed
Please update the attribute value and resume the notarization process'
'More than one attribute exists for this owner and type. The attribute referenced by <owner;type> cannot be uniquely determined (multiple attributes of the given type exist for the the given owner).
Please provide the attributeId instead of the type'

IDENTITY USE REQUESTS

Create Identity Use Request

Endpoint

POST /api/identity-use

Body Parameters

Name Type Description Required
secret string The secret of the sender
publicKey string The publicKey of the sender
asset object The request asset
identityuse object
owner string The Persona address for which the request will be created
serviceName string The name of the service for which the request will be created
serviceProvider string The provider of the service for which the request will be created
attributes array Array of <type, value> pairs with all the required attributes for the given service

Request

{"secret":"...","publicKey":"..","asset":{  
"identityuse":[{  
"owner":"LX9JSTgnd34zPQaE665qQqXdqiPfJ1gAoJ",  
"serviceName":"Ada",  
"serviceProvider":"LSDquEuwwggJJSHjqN46oNj1QWa3xaDqhD",  
"attributes":[  
{"type":"identity_card","value":"HHH"}  
]  
}]  
}  
}

Response

{ "success":true, transactionId:
'578031250c1371069bc285fca78c13407eaca0cb4b87fa0def1cb326611e5d02' }

Errors

Message Reason
'Only the owner is allowed to create an identity use request' The user that creates the use request cannot be the service provider of the request
'Cannot create identity use request : some attributes are expired or are missing required validations' Some of the attributes that are part of the request are expired or inactive ( have an insufficient number of validations for the given service)
'Cannot create identity use request : some required attribute values are not provided in the request' All attributes are active and not expired, but only some are provided in the request.
'Cannot create identity use request : missing required service attributes' Some of the attributes required by the service do not exist in the system
'An identity use request cannot be created for an inactive service' The service for which the request will be created is inactive
'A pending approval identity use request already exists' The request cannot be created because this owner already has a request that is pending approval for this service
'An active identity use request already exists' The request cannot be created because this owner already has a request that is active for this service

Get Identity Use Requests

Endpoint

GET /api/identity-use

Query Parameters

Name Type Description Required
owner string The Persona address of user for which the requests will be retrieved
serviceName string The name of the service for which the requests will be retrieved
serviceProvider string The provider of the service for which the requests will be retrieved
serviceId string The ID of the service for which the requests will be retrieved

At least one of the parameters above must be provided

If 'serviceName' is specified, then 'serviceProvider' must also be specified

Query parameter precedence:

<owner; serviceId>

serviceId

owner

<serviceName;serviceProvider>

serviceProvider

Response

A. Query made by serviceName and serviceProvider

{ success: true,

identity_use_requests:

[ { owner: 'LX9JSTgnd34zPQaE665qQqXdqiPfJ1gAoJ',

attribute_types: '["identity_card"]',

name: 'Amelie',

provider: 'LSDquEuwwggJJSHjqN46oNj1QWa3xaDqhD',

description: 'Modus',

timestamp: 56937642,

id: 1,

status: 'PENDING_APPROVAL',

reason: null,

attributes:
'[{"type":"identity_card","value":"QmXaErkZBhwTNSLcesqgmtA3shYqpvqxhdWEydtjo9SEb8"}]',

service_status: 'ACTIVE' } ],

count: 1 }

B. Query made by owner and serviceId ( validation_requests are retrieved only in this scenario )

{ success: true,

identity_use_requests:

[ { owner: 'LX9JSTgnd34zPQaE665qQqXdqiPfJ1gAoJ',

attribute_types: '["identity_card"]',

name: 'Ada',

provider: 'LSDquEuwwggJJSHjqN46oNj1QWa3xaDqhD',

description: 'Modus',

timestamp: 56937662,

id: 2,

status: 'PENDING_APPROVAL',

reason: null,

attributes:
'[{"type":"identity_card","value":"QmXaErkZBhwTNSLcesqgmtA3shYqpvqxhdWEydtjo9SEb8"}]',

service_status: 'ACTIVE' } ],

validation_requests_count: 2,

validation_requests:

[ { id: 6,

attribute_id: 20,

validator: 'LbDsDwL3vt9e35f3djJZHxWHfHGXntq3N5',

status: 'COMPLETED',

validation_type: 'FACE_TO_FACE',

type: 'identity_card' },

{ id: 9,

attribute_id: 20,

validator: 'LWBeHAE1LjaPXLsedn3aqGtNU4zw6CNkR9',

status: 'COMPLETED',

validation_type: 'FACE_TO_FACE',

type: 'identity_card' } ] }  

C. Query with no results

{"success":true,"identity_use_requests":[],"count":0}

Errors

Message Reason
'Either the attribute id, the validation request validator or the attribute owner must be provided' Incorrect parameters were provided
'Object didn't pass validation for format address: ' Incorrect Persona address was provided for the owner or serviceProvider parameters
'If the serviceName parameter is specified, the serviceProvider parameter must also be specified' The query contains the serviceName, but not the serviceProvider as well

Approve Identity Use Request

Endpoint

POST /api/identity-use/approve

Body Parameters

Name Type Description Required
secret string The secret of the sender
publicKey string The publicKey of the sender
asset object The request asset
identityuse object
owner string The Persona address for which the request will be approved
serviceName string The name of the service for which the request will be approved
serviceProvider string The provider of the service for which the request will be approved

Request

{ secret: '...', publicKey: '...',  
asset: { identityuse: [{  
"owner":"LX9JSTgnd34zPQaE665qQqXdqiPfJ1gAoJ",  
"serviceName":"Ada",  
"serviceProvider":"LSDquEuwwggJJSHjqN46oNj1QWa3xaDqhD"  
}]  
}  
}

Response

{ "success":true, transactionId:
'6d62b60538a25040719ebbfe4bf472a75fbbef9207532da68202c5f4aaad9b98' }

Errors

Message Reason
'Only the service provider is allowed to perform this action on a validation request' The user that performs the approve action must be the provider of the service of that request
'The specified identity use request must be in pending approval status The provided request must be in PENDING_APPROVAL status for the approve action to be performed
for the action to take place'
'No action can be performed on an identity use request which belongs to The service on which the request was created is now inactive, and no action can subsequently be performed on the request
an inactive service'
'There is no identity use request that is pending approval or active for this attribute' The given action (APPROVE) cannot be performed on the request, since it has a status that does not allow it to be changed. Only Pending Approval and Active requests can be answered.
'There is no identity use request for this action' The identity use request to be approved does not exist

Decline Identity Use Request

Endpoint

POST /api/identity-use/decline

Body Parameters

Name Type Description Required
secret string The secret of the sender
publicKey string The publicKey of the sender
asset object The request asset
identityuse object
owner string The Persona address for which the request will be declined
serviceName string The name of the service for which the request will be declined
serviceProvider string The provider of the service for which the request will be declined
reason string The reason for declining the request (limited to 1024 characters)

Request

{ secret: '...', publicKey: '...',  
asset: { validation: [{  
"owner":"Lguu3RdVHxdBTsT3B5z6hHd9QsHN2UyZMk",  
"serviceName":"Ada",  
"serviceProvider":"LSDquEuwwggJJSHjqN46oNj1QWa3xaDqhD",  
"reason":"some reason"  
}]  
}  
}

Response

{ "success":true, transactionId:
'030cca25405fa440277a2d226656bc281744657f805c1e66480c132d8f89a8692e' }

Errors

Message Reason
'Only the service provider is allowed to perform this action on an identity use request' The user that performs the approve action must be the service provider of that request
'The specified attribute validation request must be pending approval The provided request must be in PENDING_APPROVAL status for the approve action to be performed
for the action to take place'
'The reason for declining a request is limited to 1024 characters' The reason provided for the decline is longer than 1024 characters
'A reason must be specified when declining an identity use request' No reason is provided for the decline action
'There is no identity use request that is pending approval or active for this attribute' The given action (DECLINE) cannot be performed on the request, since it has a status that does not allow it to be changed. Only Pending Approval and Active requests can be answered.
'No action can be performed on an identity use request which belongs to an inactive service' The service on which the request was created is now inactive, and no action can subsequently be performed on the request

End Identity Use Request

Endpoint

POST /api/identity-use/end

Body Parameters

Name Type Description Required
secret string The secret of the sender
publicKey string The publicKey of the sender
asset object The request asset
identityuse object
owner string The Persona address for which the request will be ended
serviceName string The name of the service for which the request will be ended
serviceProvider string The provider of the service for which the request will be ended
reason string The reason for ending the request (limited to 1024 characters)

Request

{ secret: '...', publicKey: '...',  
asset: { identityuse: [{  
"owner":"Lguu3RdVHxdBTsT3B5z6hHd9QsHN2UyZMk",  
"serviceName":"Ada",  
"serviceProvider":"LSDquEuwwggJJSHjqN46oNj1QWa3xaDqhD"  
}]  
}  
}

Response

{ "success":true, transactionId:
'2086a2a0d773f1eecf07c6e0158caadb3017b015272c7c3d8ac391ec960aa8a5' }

Errors

Message Reason
'Only the owner is allowed to perform this action on an identity use request' The user that performs the approve action must be the owner of that request
'The specified identity use request must be active for the action to take place' The provided request must be in ACTIVE status for the approve action to be performed
'No action can be performed on an identity use request which belongs to an inactive service' The service on which the request was created is now inactive, and no action can subsequently be performed on the request
'The reason for ending a request is limited to 1024 characters' The reason provided for ending the identity use request exceeds the limit of 1024 characters
'There is no identity use request that is pending approval or active for this attribute' The given action (END) cannot be performed on the request, since it has a status that does not allow it to be changed. Only Pending Approval and Active requests can be answered.
'A reason must be specified when ending an identity use request' The action to end the identity use request was made without providing a reason

Cancel Identity Use Request

Endpoint

POST /api/identity-use/cancel

Body Parameters

Name Type Description Required
secret string The secret of the sender
publicKey string The publicKey of the sender
asset object The request asset
identityuse object
owner string The Persona address for which the request will be canceled
serviceName string The name of the service for which the request will be canceled
serviceProvider string The provider of the service for which the request will be canceled

Request

{ secret: '...', publicKey: '...',  
asset: { identityuse: [{  
"owner":"Lguu3RdVHxdBTsT3B5z6hHd9QsHN2UyZMk",  
"serviceName":"Ada",  
"serviceProvider":"LSDquEuwwggJJSHjqN46oNj1QWa3xaDqhD"  
}]  
}  
}

Response

{ "success":true, transactionId:
'3c31c46586ce38fe7ba1b32194dd8952eacc8a4336d0d7ed82cc0dde294c9e0e' }

Errors

Message Reason
'Only the service provider is allowed to perform this action on an identity use request' The user that performs the approve action must be the service provider of that request
'The specified identity use request must be in pending approval status The provided request must be in PENDING_APPROVAL status for the approve action to be performed
for the action to take place'
'There is no identity use request that is pending approval or active for this attribute' The given action (CANCEL) cannot be performed on the request, since it has a status that does not allow it to be changed. Only Pending Approval and Active requests can be answered.
'No action can be performed on an identity use request which belongs to an inactive service' The service on which the request was created is now inactive, and no action can subsequently be performed on the request

SERVICES

Create Service

Endpoint

POST /api/services

Body Parameters

Name Type Description Required
secret string The secret of the service provider user
publicKey string The publicKey of the service provider user
asset object The request asset
service object
name string The name of the service that will be created
provider string The provider of the service that will be created
description string The description of the service that will be created
validations_required integer The minimum number of completed and active validations each attribute that is part of the service must have
attributeTypes array Array of <type, value> pairs with all the required attributes for the given service

Request

{"secret":"...","publicKey":"..","asset":{  
"service":{  
"name":"serviceExample",  
"description":"descriptionExample",  
"provider":"LSDquEuwwggJJSHjqN46oNj1QWa3xaDqhD",  
"validations_required":2,  
"attributeTypes":["identity_card"]  
}  
}  
}

Response

{ "success":true, transactionId:
'0469f4ed37422d0daccbd9e37f7846e3e3220fc8242cc6d0b0856520ff6e6136' }

Errors

Message Reason
'A service with this name already exists for this provider' The provider already has a service with the same name
'The service description is limited to 2048 characters' The provided service description exceeds the limit of 2048 characters

Get Services

Endpoint

GET /api/services

Query Parameters

Name Type Description Required
name string The name based on which services will be retrieved
provider string The Persona address of the provider for which services will be retrieved
id integer The ID of the service to be retrieved
status string The status based on which services will be retrieved

Response

A. With results (by service provider)

GET /api/services?provider=LTAAFiSnPSsZXnNPGD6dg7cfy2gm4o6Fu7

{ "success":true, "services":[  
{"id":1,  
"name":"firstService",  
"provider":"LTAAFiSnPSsZXnNPGD6dg7cfy2gm4o6Fu7",  
"description":"description",  
"status":"INACTIVE",  
"timestamp":57360971,  
"attribute_types":"[\\"identity_card\\"]",  
"validations_required":2  
},  
{"id":2,  
"name":"secondService",  
"provider":"LTAAFiSnPSsZXnNPGD6dg7cfy2gm4o6Fu7",  
"description":"xyz",  
"status":"ACTIVE",  
"timestamp":57360981,  
"attribute_types":"[\\"identity_card\\"]",  
"validations_required":1}  
],  
"count":2  
}

B. With results (by service name)

GET /api/services?name=firstService

{ "success":true, "services":[  
{ "id":1,  
"name":"firstService",  
"provider":"LTAAFiSnPSsZXnNPGD6dg7cfy2gm4o6Fu7",  
"description":"description",  
"status":"INACTIVE",  
"timestamp":57360971,  
"attribute_types":"[\\"identity_card\\"]",  
"validations_required":2  
}  
],  
"count":1  
}

C. With results (by status and provider)

GET /api/services?provider=LTAAFiSnPSsZXnNPGD6dg7cfy2gm4o6Fu7&status=INACTIVE

{ "success":true, "services":[  
  
{ "id":1,  
"name":"firstService",  
"provider":"LTAAFiSnPSsZXnNPGD6dg7cfy2gm4o6Fu7",  
"description":"description",  
"status":"INACTIVE",  
"timestamp":57360971,  
"attribute_types":"[\\"identity_card\\"]",  
"validations_required":2  
}  
],  
"count":1  
}

C. Query with no results

{ success: true, services: [], count: 0 }

Get Service Attribute Types

Endpoint

GET /api/services/attributeTypes

Query Parameters

Name Type Description Required
name string The name of the service for which the required attribute types will be retrieved
provider string The Persona address of the provider of the service for which the required attribute types will be retrieved

Response

GET api/services/attributeTypes?name=firstService&provider=LTAAFiSnPSsZXnNPGD6dg7cfy2gm4o6Fu7

{"success":true,"service_attribute_types":["identity_card"]}

Errors

Message Reason
'No service was found for the given parameters' The provided name and provider do not correspond to an existing service

Inactivate Service

Endpoint

PUT /api/services/inactivate

Body Parameters

Name Type Description Required
secret string The secret of the service provider user
publicKey string The publicKey of the service provider user
asset object The request asset
service object
name string The name of the service that will be inactivated
provider string The provider of the service that will be inactivated

Request

{ "secret":"...",  
"publicKey":"...","asset":{"service":{"name":"Ali","provider":"LSDquEuwwggJJSHjqN46oNj1QWa3xaDqhD"}}}

Response

{"success":true,"transactionId":"247f8a353b47a990328f83444e7fea56c96af391f036471cc7ba6dc6fa0b4632"}

Errors

Message Reason
'No service was found for the given parameters' The service to inactivate does not exist
'The service is already inactive' The service to inactivate is already inactive