Signing Methods API Flow

This guide will explain the Signing Methods flow including API calls.

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:

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.

{
  "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:

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:

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 can be removed.

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:

• 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) 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 new Wallet and Link to User

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

POST /api/wallets

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

Request Body

{
  "pincode": "123456",
  "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": "WHITE_LABEL",
    "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:

POST /api/wallets/import

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

Request Body

{
  "importWalletType": "AETERNITY_KEYSTORE",
  "pincode": "123456",
  "keystore": "Enter_Your_Keystore_Here",
  "password": "Enter_Password_For_Keystore_Here"
}

3.3) Link Existing Wallet to User

To link an existing wallet to a user, you should use the endpoint:

PUT /api/wallets/{id}/user

Path Parameters:

{id} : This is the wallet ID of the wallet you want to link with a User.

Header Parameters:

Provide the User's 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:

In the request body you should provide:

1. pincode of the existing wallet

2. userId of the user you want to link the wallet to

This way the wallet’s PIN will be updated to match the user’s PIN signing method and the wallet will be linked to the specified user.

Request Body

{
  "pincode": "123456",
  "userId": "e85470a8-5deb-41f6-be6c-de693683a22c"
}

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

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.

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

• 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:

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.

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 signing method has been deleted.

6) Signing Transaction and Signature Requests

6.1) In the Request Body

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

Apart from the pincode, 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.

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

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