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

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

Response samples

Content type
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: is_recovery=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

Content type
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: public_ip=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

Content type
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

Content type
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:

Email verification token

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

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

Response samples

Content type
application/vnd.api+json