Context

Throughout this guide, when we mention "Users," we are referring to the individuals who will be using your service as end-users.

Signing Methods Flow

1. Create a User

First, let's see how we create a user. Normally, one user will correspond to one of your end users. This way each end user will have their own signing methods and wallets.

You can create one or multiple users and follow 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.

📘

You can create users without a specifying a signing method. The signingMethod object in body is optional.

For this example, we will create a signing method along with creating a user.

To create a user, call the following endpoint:

Request Endpoint: reference

POST /api/users

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.

{
  "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 Signing Methods

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.

In this example, we will create an additional emergency code signing method.

Call the following endpoint to create a signing method:

Request Endpoint: reference

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.

Request Body:

📘

For this example, we will create the emergency code signing method.

The body does not contain the value property because we want to autogenerate the emergency code.

{
  "type": "EMERGENCY_CODE"
}

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:

• result.id: This is the signing method ID
• result.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. Link wallets to the User

Once a wallet is linked to a user, it will be accessible with the user’s signing methods only.

You can either create a new wallet, import a wallet, or link an already existing one.

3.1 Create a new Wallet and Link to the User

To create a new wallet for a user, you should use the following endpoint:

Request Endpoint: reference

POST /api/wallets

You need to specify a userId in the request body. This way the wallet will be created and immediately linked to the specified user (userId). You should also provide this user’s signing method in the header as:

Request Body:

{
  "description": "WALLET#1",
  "secretType": "AETERNITY",
  "userId": "cc931c57-9ff0-47c2-a0ab-acf2cb5cf1de"
}

Response Body:

{
  "success": true,
  "result": {
    "id": "fce92b11-d18f-4577-b7f8-7dccfd131abf",
    "address": "ak_2DPcLNVUNiJ5msLdUcvLzvPEb981khy7tN62xP6jZSnyMva4fT",
    "walletType": "API_WALLET",
    "secretType": "AETERNITY",
    "createdAt": "2023-08-02T12:08:38.064870232",
    "archived": false,
    "description": "WALLET#1",
    "primary": false,
    "hasCustomPin": false,
    "userId": "e85470a8-5deb-41f6-be6c-de693683a22c",
    "balance": {
      "available": true,
      "secretType": "AETERNITY",
      "balance": 0,
      "gasBalance": 0,
      "symbol": "AE",
      "gasSymbol": "AE",
      "rawBalance": "0",
      "rawGasBalance": "0",
      "decimals": 18
    }
  }
}

👍

You have successfully created a wallet and linked the User.

3.2 Import a Wallet and Link User

To import a new wallet and link it to a user, you should use the endpoint:

Request Endpoint: reference

POST /api/wallets/import

Specify a userId in the request body. This way the wallet will be imported and immediately linked to the specified user. You should also provide this user’s signing method in the header as:

Request Body:

{
  "importWalletType": "AETERNITY_KEYSTORE",
  "keystore": "Enter_Your_Keystore_Here",
  "password": "Enter_Password_For_Keystore_Here",
  "userId": "aed84a79-9c65-4f13-bae1-87313cc5fbf7"
}

👍

That’s it! Once everything is set up, the users you’ve created can start using their signing methods.

4. Recovering Signing Methods

The main goal of the signing methods is for users to have different means to recover their wallets. In case a signing method’s value is lost, it can be updated by providing another valid signing method.

For example, if a user forgets their PIN, the endpoint can be called using the PIN signing method ID and the user's ID within the URL path. To authenticate, include a header that holds a valid alternate Signing-Method, which could be an emergency code or biometric.

The request body will contain the new PIN, indicated by the value parameter.

That’s done through the endpoint:

Request Endpoint: reference

PUT /api/users/{userId}/signing-methods/{signingMethodId}

Path Parameters:

{userId} : This is the ID of the User whose PIN you want to reset

{signingMethodId} : This is the ID of the User's PIN signing method

Header Parameters:

Provide the User's Signing-Method in the header request to authenticate the call. In this case, we are resetting the PIN, so you need to provide either the emergency code or biometric signing method here.

Request Body:

• value: This will be your new PIN code

{
  "value": "987654"
}

Response Body:

{
  "success": true,
  "result": {
    "id": "4658c064-05b9-4bbd-9f0e-68a9588c7bc3",
    "type": "PIN",
    "incorrectAttempts": 0,
    "remainingAttempts": 10,
    "lastUsedSuccess": "2023-08-02T12:34:57.63061",
    "hasMasterSecret": true
  }
}

👍

You have successfully reset your PIN code!

5. Deleting a Signing Method

Call the following endpoint to delete a signing method:

Request Endpoint: reference

DELETE /api/users/{userId}/signing-methods/{signingMethodId}

Path Parameters:

{userId} : This is the User ID whose signing method you want to delete.

{signingMethodId} : This is the ID of the signing method you want to delete.

Header Parameters:

Provide a valid signing method (other than the one you want to delete) in the header request to authenticate the call.

👍

You will get a 200 OK response indicating the signing method has been deleted.

6. Signing Transaction and Signature Requests

6.1 In the Request Body (DEPRECATED)

You can still use the pincode for any signing request or executing transactions. If the request is to be signed by a wallet linked to a user, we will automatically verify that the specified pincode is the same as the PIN signing method for the user.

Use the pincode property in the request body.

🚧

This applies only to the PIN signing method.

Example:

{
  "pincode" : "123456",
  "transactionRequest": 
    {
    "type" : "TRANSFER",
    "secretType" : "MATIC",
    "walletId" : "1f578c44-32cd-11ee-be56-0242ac120002",
    "to" : "0x49765De8772d810Eb76F4j8E6E5AEE0032f73AC8",
    "value": 0.1 
    }
}

6.2 In the Header

A Signing-Method parameter can also be passed in the header.

So when calling the endpoints for signing a signature request or executing a transaction, pass the Signing-Method parameter through the header with value: id:value

📘

The Signing-Method in header is used for authentication.

Example:

In this example, a PIN signing method ID (f43744a8-32c4-11ee-be56-0242ac120002), separated by a colon is used with it's value (654321)

In the header request, the Signing-Method parameter is passed with the value:

f43744a8-32c4-11ee-be56-0242ac120002:654321