Accounts

Introduction#

Account is an entity within the system representing theorically one physical person in the "real world".

It is used for 3 main reasons:

link identities together (one person can have many identities).
store a password (for authentication flow and for the use cryptographic features).
store some backup data (data used to make cryptographic features better).

An account has always an identity linked to it, it cannot exist alone. Though it is important to notice it is identities that contains that link information, considering the one (account) to many (identities) relationship.

Set a password on a identity#

This endpoint can be used to:

set a new password to an identity to setup the crypto of the account
reset the password of an identity

Request#

PUT https://api.misakey.com/accounts/:id/set-password

Cookies:

accesstoken (opaque token) (ACR >= required_acr): mid claim as the identity id.
tokentype: must be bearer

Headers:

X-CSRF-Token: a token to prevent from CSRF attacks.

Path Parameters:

id (uuid string): the account id.

JSON Body:

{
    "prehashed_password": {
      "hash_base_64": "Ym9uam91ciBmbG9yZW50IGNvbW1lbnQgdmFzLXR1IGVuIGNldHRlIGJlbGxlIGpvdXJuw6llID8h",
      "params": {
        "salt_base_64": "Yydlc3QgdmFjaGVtZW50IHNhbMOpZSBjb21tZSBwaHJhc2UgZW5jb2TDqWUgZW4gYmFzZSA2NA==",
        "memory": 1024,
        "iterations": 1,
        "parallelism": 1
      }
    },
    "secret_storage": {
      "account_root_key": {
          "key_hash": "ofUqfBb6u6mnU61XFYFBs4g",
          "encrypted_key": "SVqIxNjfDNSBLME0bTxBVg"
      },
      "vault_key": {
          "key_hash": "GRNiluqdewU0Deiw-GxDgQ",
          "encrypted_key": "RhkCn-l0OhPcRDqW4hFdeg"
      },
      "asym_keys": {
          "JTGeadip5O4-Hu6CgrndHA": {
              "encrypted_secret_key": "1dC9viP0rWxi6hPg1uKKQN9UhVYBUxebG_IV1cGCRYA"
          },
          "CppeRlQFRKn7yfQJArLEug": {
              "encrypted_secret_key": "mqmy4yZL-voAe0WxQRsO1ZofHUkpiz8y2nlaMoyKcrg"
          }
      },
      "pubkey": "6QvaldZMMtJdi1LUg4N0Ag",
      "non_identified_pubkey": "MUah4EnFPmyy6XA58WoG9A",
      "pubkey_aes_rsa": "com.misakey.aes-rsa-enc:dDLJjuwdcsTZIMJXsa6STg",
      "non_identified_pubkey_aes_rsa": "com.misakey.aes-rsa-enc:sCbt8_cgIxShuPHcKmRYrQ"
    },
  },
}

Response#

Code:

HTTP 204 NO CONTENT

Change password#

This route allows the update of an account password and the associated backup data.

The old_prehashed_password and new_prehashed_password contain information following Argon2 server relief concepts.

Request#

PUT https://api.misakey.com/accounts/:id/password

Cookies:

accesstoken (opaque token) (ACR >= 2): mid claim as the identity id.
tokentype: must be bearer

Headers:

X-CSRF-Token: a token to prevent from CSRF attacks.

Path Parameters:

id (uuid string): the account id.

JSON Body:

{
    "old_prehashed_password": {
    "hash_base_64": "Ym9uam91ciBmbG9yZW50IGNvbW1lbnQgdmFzLXR1IGVuIGNldHRlIGJlbGxlIGpvdXJuw6llID8h",
    "params": {
      "salt_base_64": "Yydlc3QgdmFjaGVtZW50IHNhbMOpZSBjb21tZSBwaHJhc2UgZW5jb2TDqWUgZW4gYmFzZSA2NA==",
      "memory": 1024,
      "iterations": 1,
      "parallelism": 1
    }  
  },
    "new_prehashed_password": {
    "hash_base_64": "Ym9uam91ciBmbG9yZW50IGNvbW1lbnQgdmFzLXR1IGVuIGNldHRlIGJlbGxlIGpvdXJuw6llID8h",
    "params": {
      "salt_base_64": "Yydlc3QgdmFjaGVtZW50IHNhbMOpZSBjb21tZSBwaHJhc2UgZW5jb2TDqWUgZW4gYmFzZSA2NA==",
      "memory": 1024,
      "iterations": 1,
      "parallelism": 1
    }  
  },
    "encrypted_account_root_key": "(unpadded URL-safe base64)",
}

old_prehashed_password (object): prehashed password using argon2:
- params (object): argon2 parameters:
  - memory (integer).
  - parallelism (integer).
  - iterations (integer).
  - salt_base_64 (base64 string).
- hash_base_64 (base64 string): the prehashed password.
new_prehashed_password (object): prehashed password using argon2:
- params (object): argon2 parameters:
  - memory (integer).
  - parallelism (integer).
  - iterations (integer).
  - salt_base_64 (base64 string).
- hash_base_64 (base64 string): the prehashed password.
encrypted_account_root_key (URL-safe base64): the account root key encrypted with the new password

Response#

Code:

HTTP 204 NO CONTENT

Get the account password parameters#

This route allows the retrieval of the account password hash parameters.

Hash parameters contains information about the way the password has been hashed following Argon2 server relief concepts.

Request#

GET https://api.misakey.com/accounts/:id/pwd-params

Response#

Code:

HTTP 200 OK

{
  "salt_base_64": "Yydlc3QgdmFjaGVtZW50IHNhbMOpZSBjb21tZSBwaHJhc2UgZW5jb2TDqWUgZW4gYmFzZSA2NA==",
  "memory": 1024,
  "iterations": 1,
  "parallelism": 1
}

memory (integer).
parallelism (integer).
iterations (integer).
salt_base_64 (base64 string).

Get the account backup#

This route allows the retrieval of the account backup using the unique account id.

Note that “account secret backup” mechanism is now read-only since the deployment of the new “secret storage” mechanism.

Request#

GET https://api.misakey.com/accounts/:id/backup

Cookies:

accesstoken (opaque token) (ACR >= 2): mid claim as an identity id linked to the account.
tokentype: must be bearer

Headers:

X-CSRF-Token: a token to prevent from CSRF attacks.

Path Parameters:

id (uuid string): the unique account id.

Response#

Code:

HTTP 200 OK

JSON Body:

{
    "data": "[STRINGIFIED JSON]",
    "version": 3
}

data (string): the user backup data.
version (integer): the current backup version.