Identity Storage (4.3.0)

Download OpenAPI specification:Download

Overview

Identity Storage uses JSON:API convention to format requests and responses. Key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Security

Request signature implementation is based on IETF HTTP Signatures draft RFC, except that implicit headers parameter is not supported; clients must explicitly specify headers used for signing. The only signature algorithm supported is ed25519-sha256, which uses public signer key as keyId. Both Signature and Authorization HTTP authentication schemas are supported. The minimum recommended data to sign are (request-header) and date.

Sign Up Flow

To have full access to the platform, a client should create their own account entity. To achieve this, the following steps must be completed.

  • create wallet

  • depending on the platform settings, additional verification may be required; for details, see email verification flow

Create Wallet

Wallet

Factor

Keychain derived using the same email/password but with different account and salt. Used as a second factor to confirm the password possession.

KDF

id - version of KDF parameters used to derive the wallet data Creates a new session.

Request Body schema: application/vnd.api+json
data
required
object (CreateWallet)
included
required
Array of One of multiple values

password is required

Responses

201

current wallet state

400

invalid request

409

wallet or recovery conflict

500

failed to save wallets or failed to create account

post /wallets

TokenD Developer Environment

https://api.achilles.tokend.io/wallets

Request samples

application/vnd.api+json
Copy
Expand all Collapse all
{
  • "data":
    {
    },
  • "included":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

Sign In Flow

The process of signing in lies in acquiring client's signing key from encrypted keychain data.

  • get KDF parameters for an existing wallet using email. If email parameter is not specified, then the default KDF will be used.

  • derive wallet id using email and password

    Wallet id is an SHA256HMAC of a key derived from wallet email and client-generated salt with the help of scrypt.

    Default KDF parameters provided by the key server should be used for each new wallet id and keychain derivation.

    Wallet id should be hex encoded.

  • get wallet with encrypted keychain data

    Get current wallet state by wallet id.

  • decrypt keychain data

    Keychain may be used to store wallet keys and any arbitrary, client-specific data.

To login with email/password, a client should store at least account id and seed.

KDF

KDF params

Returns current default derivation parameters or parameters used to derive a particular wallet.

Parameters

email - will return KDF parameters for wallet keychain, 404 Not Found if email is unknown.

is_recovery - boolean denoting if the client wants to get KDF for the recovery keychain.

If the email parameter is not specified, the default KDF will be used.

query Parameters
email
string

will return KDF parameters for the wallet keychain

is_recovery
string
Example: false

boolean denoting whether or not the client wants to get KDF for the recovery keychain

Responses

200

Success

404

KDF not found

500

Internal Error

get /kdf

TokenD Developer Environment

https://api.achilles.tokend.io/kdf

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

Get Wallet

Wallet

Returns wallet by its id. Creates a new session.

path Parameters
wallet-id
required
string

id of wallet

query Parameters
public_ip
string
Example: false

if public_ip = true client`s ip is not saved

Responses

200

Success

403

wallet verificationor additional factor required

404

wallet not found

get /wallets/{wallet-id}

TokenD Developer Environment

https://api.achilles.tokend.io/wallets/{wallet-id}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    },
  • "included":
    [
    ]
}

Email Verification Flow

Depending on the implementation, TokenD system can require email verifications. If this is the case, then any attempt to get user's wallet will be failed with 403 Forbidden error.

After the wallet creation, a user will receive an email letter with a verification link.

To verify an email, a user has to follow the link in the verification message. Verification link contains client router payload with meta fields token and wallet id. Use this values for the wallet verification request.

Request Verification

Requesting verification resend

Instant delivery is not guaranteed.

path Parameters
wallet-id
required
string

related wallet id

Responses

204

token created

400

email already confirmed

500

failed to get token

post /wallets/{wallet-id}/verification

TokenD Developer Environment

https://api.achilles.tokend.io/wallets/{wallet-id}/verification

Response samples

application/vnd.api+json
Copy
Expand all Collapse all
{
  • "errors":
    [
    ]
}

Verify Wallet

Verify Wallet

After the wallet is created (and verified is false), a user should receive an email with the verification link with client router payload

path Parameters
wallet-id
required
string

related wallet id

Request Body schema:
data
object (VerificationRequest)

Responses

204

Wallet was verified

400

invalid input parameters

500

failed to verify token

put /wallets/{wallet-id}/verification

TokenD Developer Environment

https://api.achilles.tokend.io/wallets/{wallet-id}/verification

Request samples

Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

Response samples

application/vnd.api+json
Copy
Expand all Collapse all
{
  • "errors":
    [
    ]
}

KYC Recovery Flow

To perform the kyc recovery, a user has to update wallet (this process is similar to changing wallet id, yet is slightly different)

  • obtain KDF parameters with email and the is_recovery flag set to true

  • generate new account id that will be used as signer for initiating kyc recovery.

  • perform a wallet update request with the new keychain_data, recovery-wallet type and new signer relation. New wallet id should be used during the wallet update.

KDF

KDF params

Returns current default derivation parameters or parameters used to derive a particular wallet.

Parameters

email - will return KDF parameters for wallet keychain, 404 Not Found if email is unknown.

is_recovery - boolean denoting if the client wants to get KDF for the recovery keychain.

If the email parameter is not specified, the default KDF will be used.

query Parameters
email
string

will return KDF parameters for the wallet keychain

is_recovery
string
Example: false

boolean denoting whether or not the client wants to get KDF for the recovery keychain

Responses

200

Success

404

KDF not found

500

Internal Error

get /kdf

TokenD Developer Environment

https://api.achilles.tokend.io/kdf

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

Update Wallet

Update Wallet

Similar to the wallet creation, but it also contains additional transaction resource used to update account signers or new signer as relation and new wallet-id as url parameter for KYC recovery.

Wallet changes will be commited only if blockchain transaction submission has been successful.

Successful request might update wallet id if the new password were used during the derivation.

🔒 An owner's signature is needed

Transaction

envelope - base64 encoded transaction envelope used to update account signers

path Parameters
wallet-id
required
string

id of wallet

query Parameters
public_ip
string
Example: false

if public_ip = true client`s ip is not saved

Request Body schema: application/vnd.api+json
data
required
UpdateWallet (object) or KYCRecoveryWallet (object)
included
required
Array of TransactionEnvelope (object) or Password (object) 2 items

transaction is required when updating wallet

Responses

200

Success

400

invalid request

401

not allowed

403

additional factor required

404

wallet not found

409

wallet already exist

500

failed to update wallet

put /wallets/{wallet-id}

TokenD Developer Environment

https://api.achilles.tokend.io/wallets/{wallet-id}

Request samples

application/vnd.api+json
Copy
Expand all Collapse all
{
  • "data":
    {
    },
  • "included":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

Wallet

Wallet exists entirely on the key server, and its purpose is to hold encrypted user data and provide additional authentication means such as 2FA and email confirmation. Wallets are identified by a wallet id that is derived from email and password.

Wallet id derivation

Wallet id is a SHA256 HMAC of scrypt key derived from wallet email and client-generated salt.

Default KDF parameters provided by the key server should be used for each new wallet id and keychain derivation.

Wallet id should be hex encoded.

Keychain derivation

Keychain may be used to store wallet keys and any arbitrary, client-specific data.

To login with email/password, a client should store at least account id and seed.

Wallet

Factor

Keychain derived using the same email/password but with different account and salt. Used as a second factor to confirm the password possession.

KDF

id - version of KDF parameters used to derive the wallet data Creates a new session.

Request Body schema: application/vnd.api+json
data
required
object (CreateWallet)
included
required
Array of One of multiple values

password is required

Responses

201

current wallet state

400

invalid request

409

wallet or recovery conflict

500

failed to save wallets or failed to create account

post /wallets

TokenD Developer Environment

https://api.achilles.tokend.io/wallets

Request samples

application/vnd.api+json
Copy
Expand all Collapse all
{
  • "data":
    {
    },
  • "included":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

Wallet

Returns wallet by its id. Creates a new session.

path Parameters
wallet-id
required
string

id of wallet

query Parameters
public_ip
string
Example: false

if public_ip = true client`s ip is not saved

Responses

200

Success

403

wallet verificationor additional factor required

404

wallet not found

get /wallets/{wallet-id}

TokenD Developer Environment

https://api.achilles.tokend.io/wallets/{wallet-id}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    },
  • "included":
    [
    ]
}

Remove Wallet Deprecated

Delete the specified wallet

🔒 An admin's signature is needed

path Parameters
wallet-id
required
string

id of wallet

query Parameters
public_ip
string
Example: false

if public_ip = true client`s ip is not saved

Responses

204

deleted

401

not allowed

500

failed to delete wallet

delete /wallets/{wallet-id}

TokenD Developer Environment

https://api.achilles.tokend.io/wallets/{wallet-id}

Update Wallet

Similar to the wallet creation, but it also contains additional transaction resource used to update account signers or new signer as relation and new wallet-id as url parameter for KYC recovery.

Wallet changes will be commited only if blockchain transaction submission has been successful.

Successful request might update wallet id if the new password were used during the derivation.

🔒 An owner's signature is needed

Transaction

envelope - base64 encoded transaction envelope used to update account signers

path Parameters
wallet-id
required
string

id of wallet

query Parameters
public_ip
string
Example: false

if public_ip = true client`s ip is not saved

Request Body schema: application/vnd.api+json
data
required
UpdateWallet (object) or KYCRecoveryWallet (object)
included
required
Array of TransactionEnvelope (object) or Password (object) 2 items

transaction is required when updating wallet

Responses

200

Success

400

invalid request

401

not allowed

403

additional factor required

404

wallet not found

409

wallet already exist

500

failed to update wallet

put /wallets/{wallet-id}

TokenD Developer Environment

https://api.achilles.tokend.io/wallets/{wallet-id}

Request samples

application/vnd.api+json
Copy
Expand all Collapse all
{
  • "data":
    {
    },
  • "included":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

Requesting verification resend

Instant delivery is not guaranteed.

path Parameters
wallet-id
required
string

related wallet id

Responses

204

token created

400

email already confirmed

500

failed to get token

post /wallets/{wallet-id}/verification

TokenD Developer Environment

https://api.achilles.tokend.io/wallets/{wallet-id}/verification

Response samples

application/vnd.api+json
Copy
Expand all Collapse all
{
  • "errors":
    [
    ]
}

Verify Wallet

After the wallet is created (and verified is false), a user should receive an email with the verification link with client router payload

path Parameters
wallet-id
required
string

related wallet id

Request Body schema:
data
object (VerificationRequest)

Responses

204

Wallet was verified

400

invalid input parameters

500

failed to verify token

put /wallets/{wallet-id}/verification

TokenD Developer Environment

https://api.achilles.tokend.io/wallets/{wallet-id}/verification

Request samples

Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

Response samples

application/vnd.api+json
Copy
Expand all Collapse all
{
  • "errors":
    [
    ]
}

2FA

Factors

Returns list of factors used for 2FA

path Parameters
wallet-id
required
string

id of a wallet

Responses

200

Success

404

wallet not found

500

failed to update wallet

get /wallets/{wallet-id}/factors

TokenD Developer Environment

https://api.achilles.tokend.io/wallets/{wallet-id}/factors

Response samples

application/vnd.api+json
Copy
Expand all Collapse all
{
  • "data":
    [
    ]
}

Factor

Creates non-active TFA factor of given type

🔒 An owner's signature is needed

path Parameters
wallet-id
required
string

id of a wallet

Request Body schema: application/json
data
required
object (TFAKey)

Responses

200

Success

400

invalid request

401

not allowed

403

factor check failed

404

wallet not found

409

factor should be created during the signup

500

failed to get wallet, failed to generate backend, failed to save backend

post /wallets/{wallet-id}/factors

TokenD Developer Environment

https://api.achilles.tokend.io/wallets/{wallet-id}/factors

Request samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

Factor

Deletes the given factor

🔒 An owner's signature is needed

path Parameters
wallet-id
required
string

id of a wallet

backend
required
string

id of a factor

Responses

200

Success

400

invalid request

401

not allowed

403

additional factor required

404

backend not found

500

failed to get backend