Identity Storage (4.7.7)
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.
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
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
current wallet state
invalid request
wallet or recovery conflict
failed to save wallets or failed to create account
TokenD Developer Environment
Request samples
- Payload
{- "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=="
}
}
]
}Response samples
- 201
{- "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.
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
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
Success
KDF not found
Internal Error
TokenD Developer Environment
Response samples
- 200
{- "data": {
- "type": "kdf",
- "id": 2,
- "attributes": {
- "algorithm": "scrypt",
- "bits": 256,
- "n": 4096,
- "r": 8,
- "p": 1,
- "salt": "E8C7204F5E3E91FA87662308B7E459F01757B005C647E49A7A49AEF32845D868"
}
}
}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 |
Responses
Success
wallet verificationor additional factor required
wallet not found
TokenD Developer Environment
Response samples
- 200
- 403
{- "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.
Requesting verification resend
Instant delivery is not guaranteed.
path Parameters
| wallet-id required | string related wallet id |
Responses
token created
email already confirmed
failed to get token
TokenD Developer Environment
Response samples
- 400
- 500
{- "errors": [
- {
- "title": "Bad Request",
- "detail": "Request body was expected",
- "status": 400
}
]
}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: application/json
Email verification token
| data | object (VerificationRequest) |
Responses
Wallet was verified
invalid input parameters
failed to verify token
TokenD Developer Environment
Request samples
- Payload
{- "data": {
- "type": "wallet_verification",
- "attributes": {
- "token": "JOqIgfCNSjnGWDrTPWbW"
}
}
}