Download OpenAPI specification:Download
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.
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
.
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
Keychain derived using the same email/password but with different account and salt. Used as a second factor to confirm the password possession.
id
- version of KDF parameters used to derive the wallet data
Creates a new session.
data required | object (CreateWallet) |
included required | Array of One of multiple values password is required |
current wallet state
invalid request
wallet or recovery conflict
failed to save wallets or failed to create account
TokenD Developer Environment
{- "data": {
- "type": "wallet",
- "id": "388108095960430b80554ac3efb6807a9f286854033aca47f6f466094ab50876",
- "attributes": {
- "account_id": "GBSR6JG5AYSAW7HK6EGJFYVIVN54LVGSY3ZLJ6X3IBQZ766EJABCZQTH",
- "salt": "qonp0sJgd30NQ916fzpO2A==",
- "keychain_data": "eyJJViI6IlRaRHppWWRTNEdKMjBYbi...RlTmFtZSI6ImdjbSJ9",
- "verification_code": "Q916"
}, - "relationships": {
- "password": {
- "data": {
- "id": "passwordID",
- "type": "password"
}
}, - "factor": {
- "data": {
- "type": "password",
- "id": "id"
}
}, - "kdf": {
- "data": {
- "type": "kdf",
- "id": 2
}
}, - "referrer": {
- "data": {
- "id": "id",
- "type": "referrer"
}
}, - "signers": [
- {
- "id": "GBSR6JG5AYSAW7HK6EGJFYVIVN54LVGSY3ZLJ6X3IBQZ766EJABCZQTH",
- "type": "signer"
}
]
}
}, - "included": [
- {
- "id": "passwordID",
- "type": "password",
- "attributes": {
- "account_id": "GBSR6JG5AYSAW7HK6EGJFYVIVN54LVGSY3ZLJ6X3IBQZ766EJABCZQTH",
- "keychain_data": "eyJJViI6IlRaRHppWWRTNEdKMjBYbisiLCJjaXBo...CJtb2RlTmFtZSI6ImdjbSJ9",
- "salt": "qonp0sJgd30NQ916fzpO2A=="
}
}
]
}
{- "data": {
- "type": "wallet",
- "id": "388108095960430b80554ac3efb6807a9f286854033aca47f6f466094ab50876",
- "attributes": {
- "account_id": "GBSR6JG5AYSAW7HK6EGJFYVIVN54LVGSY3ZLJ6X3IBQZ766EJABCZQTH",
- "keychain_data": "eyJJViI6IlRaRHppWWRTNEdKMjBYbisiLCJjaXBo...CJtb2RlTmFtZSI6ImdjbSJ9",
- "verified": true,
- "last_sent_at": "2018-11-23T16:35:11Z"
}, - "relationships": {
- "password": {
- "data": {
- "type": "password",
- "id": "id"
}
}, - "kdf": {
- "data": {
- "type": "kdf",
- "id": 2
}
}, - "factor": {
- "data": {
- "type": "password",
- "id": "id"
}
}, - "referrer": {
- "data": {
- "id": "id",
- "type": "referrer"
}
}, - "session": {
- "data": {
- "id": "01D78XYFJ1PRM1WPBCBT3VHMNV",
- "type": "sessions"
}
}
}
}
}
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
.
Returns current default derivation parameters or parameters used to derive a particular wallet.
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.
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 |
Success
KDF not found
Internal Error
TokenD Developer Environment
{- "data": {
- "type": "kdf",
- "id": 2,
- "attributes": {
- "algorithm": "scrypt",
- "bits": 256,
- "n": 4096,
- "r": 8,
- "p": 1,
- "salt": "E8C7204F5E3E91FA87662308B7E459F01757B005C647E49A7A49AEF32845D868"
}
}
}
Returns wallet by its id. Creates a new session.
wallet-id required | string id of wallet |
public_ip | string Example: public_ip=false if |
Success
wallet verificationor additional factor required
wallet not found
TokenD Developer Environment
{- "data": {
- "type": "wallet",
- "id": "388108095960430b80554ac3efb6807a9f286854033aca47f6f466094ab50876",
- "attributes": {
- "account_id": "GBSR6JG5AYSAW7HK6EGJFYVIVN54LVGSY3ZLJ6X3IBQZ766EJABCZQTH",
- "keychain_data": "eyJJViI6IlRaRHppWWRTNEdKMjBYbisiLCJjaXBo...CJtb2RlTmFtZSI6ImdjbSJ9",
- "verified": true,
- "last_sent_at": "2018-11-23T16:35:11Z"
}, - "relationships": {
- "password": {
- "data": {
- "type": "password",
- "id": "id"
}
}, - "kdf": {
- "data": {
- "type": "kdf",
- "id": 2
}
}, - "factor": {
- "data": {
- "type": "password",
- "id": "id"
}
}, - "referrer": {
- "data": {
- "id": "id",
- "type": "referrer"
}
}, - "session": {
- "data": {
- "id": "01D78XYFJ1PRM1WPBCBT3VHMNV",
- "type": "sessions"
}
}
}
}, - "included": [
- {
- "id": "01D78XYFJ1PRM1WPBCBT3VHMNV",
- "type": "sessions",
- "attributes": {
- "expires_at": "2019-05-29T16:44:58Z",
- "encryption_key": "f95d70b7ffae669d0bc24d247a9b517ecbde8c636d1e8ab3bbb7f8b0bddd3f9f"
}
}
]
}
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.
Instant delivery is not guaranteed.
wallet-id required | string related wallet id |
token created
email already confirmed
failed to get token
TokenD Developer Environment
{- "errors": [
- {
- "title": "Bad Request",
- "detail": "Request body was expected",
- "status": 400
}
]
}
After the wallet is created (and verified
is false), a user should receive an email with the verification link with client router payload
wallet-id required | string related wallet id |
Email verification token
data | object (VerificationRequest) |
Wallet was verified
invalid input parameters
failed to verify token
TokenD Developer Environment
{- "data": {
- "type": "wallet_verification",
- "attributes": {
- "token": "JOqIgfCNSjnGWDrTPWbW"
}
}
}