User Management

This guide will take you through the API calls for creating, deleting, updating, and managing users.

Disclaimer!
All wallets created will be non-custodial. 
When you create a user and link a wallet to them, we recommend creating an additional signing method (EMERGENCY CODE). This ensures that your users have a means to reset their PIN in case it is lost. 
Failure to create an emergency code means that if a user loses their PIN, they will permanently lose access to their wallet.
Context
Throughout this guide, when we mention "Users," we are referring to the individuals who will be using your service as end-users.
Introduction
Each User corresponds to one of your end-user. If you don’t have end users, you can still use the “User” concept without those corresponding to actual end users. 
You can create multiple Users, and all of them can have a different signing methods and multiple wallets linked to them via Wallet-API.
​Click here to read about Signing Methods.​
You can create:
One User and have multiple wallets linked to them
Multiple users and all of them can have one or more wallets
The Wallet-API allows you add a reference when creating a User. This reference parameter can be virtually anything that describes a User. It helps you tell one User apart from another. 
Let's see how you can create a User.
1) Create a User
You can create one or multiple users using the same flow. If you create only one user and link all wallets to it, then all wallets will be accessible with the signing methods you create for this user.
The signingMethod object in body is optional. You can create users without a specifying a signing method. 
For this example, we will create a signing method along with creating a user.
To create a user, call the following endpoint:
​POST /api/users 
Request Body Parameters:
Parameter
Type
Required
Description
reference
string
    ❌
You can provide a reference (can be whatever you want) to distinguish between users.
signingMethod
object
    ❌
This object contains the type of signing method and it’s value.
type
string
    ❌
This parameter indicates the type of signing method. (e.g., PIN, EMERGENCY_CODE, BIOMETRIC.)
The first signing method should always be a PIN.
value
string
    ❌
This is the value of your signing method. For example, the value for PIN can be “123456”.
Request Body: 
{
  "reference": "ABD User 1",
  "signingMethod": {
    "type": "PIN",
    "value": "123456"
  }
}
Response Body:
Save the following parameters from the response body. They will be used later in the guide.
result >> id: This is the User ID. Every user you create will have a unique user ID.
signingMethods >> id: This is the signing method ID and will be used for authentication purposes. Every signing method will have a different and unique ID.
It is IMPORTANT to save the PIN signing method ID since it is used during the PIN reset process, or when creating an additional signing method.
{
  "success": true,
  "result": {
    "id": "e85470a8-5deb-41f6-be6c-de693683a22c",
    "reference": "ABD User 1",
    "createdAt": "2023-08-02T07:18:58.624685414",
    "signingMethods": [
      {
        "id": "4658c064-05b9-4bbd-9f0e-68a9588c7bc3",
        "type": "PIN",
        "incorrectAttempts": 0,
        "remainingAttempts": 10,
        "hasMasterSecret": true
      }
    ]
  }
}
2) Create Emergency Code (recommended)
In this example, we will create an additional emergency code signing method. This emergency code can be used to reset a forgotten PIN code, sign transactions, and to authenticate calls.
When creating a signing method for a user for the first time, you don’t have to provide another one. 
When creating additional signing methods, you will have to provide an existing valid signing method in the header.
Call the following endpoint to create an emergency code:
​POST /api/users/{userId}/signing-methods​
Path Parameters:
{userId} : This is the User ID whose signing method you want to create. Paste the previously saved User ID here.
Header Parameters:
For this example, the user already has an existing PIN signing method, that's why we are providing the PIN signing method in the header request to authenticate the call.
Parameter
Value
Description
Signing-Method
id:value
​
id: This is the ID of the signing method
value: This is the value of the signing method
Request Body Parameters:
{
  "type": "EMERGENCY_CODE"
}
The body does not contain the value property because we want to autogenerate the emergency code.
Parameter
Type
Description
type
string
This parameter indicates the type of signing method. (e.g., PIN, EMERGENCY_CODE, BIOMETRIC.)
value
string
This is the value of your signing method. For example, the value for EMERGENCY_CODE can be “w2v7yertaad21lhudqghzwcg4”.
To autogenerate the emergency code, this field can be removed.
For this example, we are creating the emergency code signing method.
Response Body:
It is IMPORTANT to save the PIN signing method ID since it is used during the PIN reset process.
Description of parameters under the result object:
id: This is the signing method ID
value: This is the value of the generated emergency code
{
  "success": true,
  "result": {
    "id": "3eccfcef-467a-42a6-8b6b-6ffce3b3b115",
    "type": "EMERGENCY_CODE",
    "incorrectAttempts": 0,
    "remainingAttempts": 10,
    "value": "taif7dxjikhtb82zm7u93tn26",
    "hasMasterSecret": true
  }
}
3) Update reference of a User
Call the following endpoint and add the new reference in the request body:
​PUT /api/users/{userId} 
Path Parameter:
{userId} : This is the ID of the User whose reference you want to update
Request Body:
{
  "reference": "Add the new updated reference here."
}
Response Body:
{
  "success": true,
  "result": {
    "id": "9cf9228e-1f2b-4940-9508-4335064cbc76",
    "reference": "Add the new updated reference here.",
    "createdAt": "2023-08-07T14:04:54.262619"
  }
}
4) Get Details of all your Users
This endpoint can be used for getting all users you’ve created and their signing methods:
​GET /api/users​
Query Parameters:
Parameter
Type
Required
Description
page
integer
    ❌
This parameter is used to specify the page number.
size
integer
    ❌
This indicates the number of users to output per page.
sortOn
string
    ❌
The name of the field that you want the results to be sorted by, such as createdAt.
sortOrder
string
    ❌
This is to show the results in ascending or descending order. The value for this can only be ASC or DESC. The default value is ASC.
reference
string
    ❌
This is used to filter your users based on the labels(reference) you've assigned.
includeSigningMethods
boolean
    ❌
This "Boolean" indicates whether to display the details of signing methods for users or not.
Response Body:
{
  "success": true,
  "pagination": {
    "pageNumber": 2,
    "pageSize": 1,
    "numberOfPages": 10,
    "numberOfElements": 10,
    "hasNextPage": true,
    "hasPreviousPage": false
  },
  "result": [
    {
      "id": "00f008b1-5e78-4f3b-9d41-8d11d953497a",
      "reference": "d",
      "createdAt": "2023-07-28T10:19:19.184984",
      "signingMethods": [
        {
          "id": "dc3218e9-a8e8-4dca-a8cb-66ebfd2701a6",
          "type": "EMERGENCY_CODE",
          "incorrectAttempts": 0,
          "remainingAttempts": 10,
          "hasMasterSecret": true
        },
        {
          "id": "ca265520-e33b-4d96-91b7-cc3eceee345d",
          "type": "PIN",
          "incorrectAttempts": 0,
          "remainingAttempts": 10,
          "hasMasterSecret": true
        }
      ]
    }
  ]
}
5) Get details of a specific User
This endpoint can be used for getting information about a specific user you’ve created and their signing methods:
​GET /api/users/{userId} 
Path Parameter:
{userId} : This is the ID of the specific User whose information you want
Response Body:
{
  "success": true,
  "result": {
    "id": "9b4414c7-d033-4cba-9635-a535d31d7030",
    "reference": "USER-A",
    "createdAt": "2023-08-03T14:23:16.037191",
    "signingMethods": [
      {
        "id": "3355c892-31af-4260-87a3-a68175bcfea5",
        "type": "PIN",
        "incorrectAttempts": 0,
        "remainingAttempts": 10,
        "lastUsedSuccess": "2023-08-04T12:34:36.752094",
        "hasMasterSecret": true
      },
      {
        "id": "38ee7ad2-043d-4c38-9b5b-b962d23e7c8e",
        "type": "EMERGENCY_CODE",
        "incorrectAttempts": 0,
        "remainingAttempts": 10,
        "hasMasterSecret": true
      }
    ]
  }
}
6) Delete a User
This endpoint can be used for deleting a User. If there are any wallets linked to the user, they will be deleted as well.
​DELETE /api/users/{userId}​
Path Parameter:
{userId} : This is the ID of the specific User you want to delete
Header Parameter:
Provide a valid signing method in the header request to authenticate the call.
Parameter
Value
Description
Signing-Method
id:value
​
id: This is the ID of the signing method
value: This is the value of the signing method
You will get a 200 OK response indicating the user is deleted. 
7) Signing Methods for Users
Each User has their unique signing method which is used for authentication purpose and for signing transactions. They are the gateway to access their wallets.
All Users have a PIN signing method but they can also have an additional EMERGENCY_CODE and BIOMETRIC signing method.
While managing your Users, you can create, update, recover, and delete their signing methods.
​Click here for more information on managing Signing Methods for Users.​
8) Link Wallet(s) to Users
There are three ways you can link wallets to your users:
1.​Create new wallet & link​
2.​Import wallet and link​
3.​Link an existing wallet​

Parameter	Type	Required	Description
`reference`	string	❌	You can provide a reference (can be whatever you want) to distinguish between users.
`signingMethod`	object	❌	This object contains the type of signing method and it’s value.
`type`	string	❌	This parameter indicates the type of signing method. (e.g., PIN, EMERGENCY_CODE, BIOMETRIC.) The first signing method should always be a PIN.
`value`	string	❌	This is the value of your signing method. For example, the value for PIN can be “123456”.

Parameter	Value	Description
`Signing-Method`	`id:value`	`id`: This is the ID of the signing method `value`: This is the value of the signing method

Parameter	Type	Description
`type`	string	This parameter indicates the type of signing method. (e.g., PIN, EMERGENCY_CODE, BIOMETRIC.)
`value`	string	This is the value of your signing method. For example, the value for EMERGENCY_CODE can be “w2v7yertaad21lhudqghzwcg4”. To autogenerate the emergency code, this field can be removed.

Parameter	Type	Required	Description
`page`	integer	❌	This parameter is used to specify the page number.
`size`	integer	❌	This indicates the number of users to output per page.
`sortOn`	string	❌	The name of the field that you want the results to be sorted by, such as `createdAt`.
`sortOrder`	string	❌	This is to show the results in ascending or descending order. The value for this can only be `ASC` or `DESC`. The default value is `ASC`.
`reference`	string	❌	This is used to filter your users based on the labels(`reference`) you've assigned.
`includeSigningMethods`	boolean	❌	This "Boolean" indicates whether to display the details of signing methods for users or not.

Parameter	Value	Description
`Signing-Method`	`id:value`	`id`: This is the ID of the signing method `value`: This is the value of the signing method

Custodial vs. Non-Custodial Wallets

Key Infrastructure and PIN Code Management

Last modified 20d ago

User Management

Disclaimer!

Context

Introduction

1) Create a User

​POST /api/users

Request Body Parameters:

Request Body:

Response Body:

2) Create Emergency Code (recommended)

​POST /api/users/{userId}/signing-methods​

Path Parameters:

Header Parameters:

Request Body Parameters:

Response Body:

3) Update reference of a User

​PUT /api/users/{userId}

Path Parameter:

Request Body:

Response Body:

4) Get Details of all your Users

​GET /api/users​

Query Parameters:

Response Body:

5) Get details of a specific User

​GET /api/users/{userId}

Path Parameter:

Response Body:

6) Delete a User

​DELETE /api/users/{userId}​

Path Parameter:

Header Parameter:

7) Signing Methods for Users

8) Link Wallet(s) to Users

POST /api/users

POST /api/users/{userId}/signing-methods

3) Update `reference` of a User

PUT /api/users/{userId}

GET /api/users

GET /api/users/{userId}

DELETE /api/users/{userId}