Server API

The fxa-auth-db-mysql has the following API which the fxa-auth-server uses.

Overview

All responses are of the form application/json.

URL Structure

All requests ...

Request Format

All requests conform to the following points:

the methods used are HEAD, GET, PUT, POST and DELETE
the Content-Type header must be application/json
all buffer-type parameters must be a hex encoded string
the body is a JSON structure

Some requests require you to substitute in a parameter as part of the path. For example, when creating an account (e.g. for the uid 'ABCD') the path used will be documented as /account/<uid> and the path used will be /account/ABCD.

Response Format

All responses conform to the following:

the returned Content-Type is always application/json
the body is a JSON structure

Data Types

The following datatypes are used throughout this document:

epoch : the date in ms since epoch. eg. 1424819640738 such as that returned from Date.now()
hex128 : a 128 bit value in hex encoding. ie. 32 chars long (16 bytes)
hex256 : a 256 bit value in hex encoding. ie. 64 chars long (32 bytes)
hex768 : a 768 bit value in hex encoding. ie. 192 chars long (96 bytes)
hex : a hex string representing n bytes of binary data.
string255 : a string up to 255 characters/bytes long

Operations

General:
- ping : GET /
- heartbeat : GET /__heartbeat__
Account:
- account : GET /account/:id
- accountExists : HEAD /emailRecord/:id
- emailRecord : GET /emailRecord/:id
- createAccount : PUT /account/:id
- checkPassword : POST /account/:id/checkPassword
- resetAccount : POST /account/:id/reset
- resetTokens : POST /account/:id/resetTokens
- deleteAccount : DELETE /account/:id
- verifyEmail : POST /account/:id/verifyEmail
- sessions : GET /account/:id/sessions
- devices : GET /account/:id/devices
- deviceFromTokenVerificationId : GET /account/:id/tokens/:tokenVerificationId/device
Devices:
- createDevice : PUT /account/:id/device/:deviceId
- updateDevice : POST /account/:id/device/:deviceId/update
- deleteDevice : DELETE /account/:id/device/:deviceId
Session Tokens:
- sessionToken : GET /sessionToken/:id
- deleteSessionToken : DELETE /sessionToken/:id
- createSessionToken : PUT /sessionToken/:id
- updateSessionToken : POST /sessionToken/:id/update
Account Reset Tokens:
- accountResetToken : GET /accountResetToken/:id
- deleteAccountResetToken : DELETE /accountResetToken/:id
Key Fetch Tokens:
- keyFetchToken : GET /keyFetchToken/:id
- keyFetchTokenWithVerificationStatus : GET /keyFetchToken/:id/verified
- deleteKeyFetchToken : DELETE /keyFetchToken/:id
- createKeyFetchToken : PUT /keyFetchToken/:id
Password Change Tokens:
- passwordChangeToken : GET /passwordChangeToken/:id
- deletePasswordChangeToken : DELETE /passwordChangeToken/:id
- createPasswordChangeToken : PUT /passwordChangeToken/:id
Password Forgot Tokens:
- passwordForgotToken : GET /passwordForgotToken/:id
- deletePasswordForgotToken : DELETE /passwordForgotToken/:id
- createPasswordForgotToken : PUT /passwordForgotToken/:id
- updatePasswordForgotToken : POST /passwordForgotToken/:id/update
- forgotPasswordVerified : POST /passwordForgotToken/:id/verified
Unverified tokens:
- verifyTokens : POST /tokens/:tokenVerificationId/verify
- verifyTokensWithMethod : POST /tokens/:tokenId/verifyWithMethod
Sign-in codes
- createSigninCode : PUT /signinCodes/:code
- consumeSigninCode : POST /signinCodes/:code/consume
TOTP tokens:
- createTotpToken : PUT /totp/:id
- totpToken : GET /totp/:id
- deleteTotpToken : DELETE /totp/:id
- updateTotpToken : POST /totp/:id/update
Recovery codes:
- replaceRecoveryCodes : POST /account/:id/recoveryCodes
- consumeRecoveryCode : POST /account/:id/recoveryCodes/:code
Recovery keys:
- createRecoverykey : POST /account/:id/recoveryKeys
- getRecoveryKey : GET /account/:id/recoveryKeys/:recoveryKeyId
- deleteRecoveryKey : DELETE /account/:id/recoveryKeys/:recoveryKeyId

Ping : `GET /`

Request

curl -X GET http://localhost:8000/

Response

HTTP/1.1 200 OK

{"version":"0.30.0"}

The server does not return any errors from this operation, except those generated by infrastructure such as a timeout, or if your library cannot connect to the server.

Heartbeat : `GET /heartbeat`

Request

curl -X GET http://localhost:8000/__heartbeat__

Response

HTTP/1.1 200 OK

{}

A failed request may be returned as:

HTTP/1.1 500 Internal Server Error

{"message":"connect ECONNREFUSED"}

This may be due to the backend server not being able to ping it's datastore, or if there happens to be any other reason the server isn't functioning correctly.

createAccount : `PUT /account/<uid>`

Example

curl \
    -v \
    -X PUT \
    -H "Content-Type: application/json" \
    -d '{
        "normalizedEmail" : "foo@example.com",
        "email"           : "foo@example.com",
        "emailCode"       : "9b4da6ccd05e7c24ce6a6c0d208bc7c9",
        "emailVerified"   : false,
        "kA"              : "5e1994b0159081921adb416236058d92bd0715a91c884654e4269c49d467a160",
        "wrapWrapKb"      : "a746589a4d3db2b0552476bae4fc8c9156d29499eeb0d6583ffd6ddcd7482097",
        "authSalt"        : "d870b1472524fcef2cfd512533b1fb19fe6cf1b555cb5d85d60a636cc5356aba",
        "verifyHash"      : "5791981c2f0685aa9400597b6bee51d04c59399798e9bcf3cdbeec3d8b50971f",
        "verifierVersion" : 1,
        "verifierSetAt"   : 1424832691282,
        "locale"          : "en_US"
    }' \
    http://localhost:8000/account/6044486dd15b42e08b1fb9167415b9ac

Request

Method : PUT
Path : /account/<uid>
- uid : hex128
Params:
- normalizedEmail : string255
- email : string255
- emailCode : hex128
- emailVerified : boolean
- kA : hex256
- wrapWrapKb : hex256
- authSalt : hex256
- verifierVersion : int8
- verifyHash hex256
- verifierSetAt : epoch
- locale : string255
- createdAt : epoch

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2

{}

Status Code : 200 OK
- Content-Type : 'application/json'
- Body : {}
Status Code : 409 Conflict
- Conditions: if this account uid or normalizedEmail already exists
- Content-Type : 'application/json'
- Body : {"message":"Record already exists"}
Status Code : 500 Internal Server Error
- Conditions: if something goes wrong on the server
- Content-Type : 'application/json'
- Body : {"code":"InternalError","message":"......"}

GET /account/

Example

curl \
    -v \
    -X GET \
    http://localhost:8000/account/6044486dd15b42e08b1fb9167415b9ac

Request

Method : GET
Path : /account/<uid>
- uid : hex128
Params: none

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 564

{
    "normalizedEmail":"foo@example.com",
    "email":"foo@example.com",
    "emailCode":"9b4da6ccd05e7c24ce6a6c0d208bc7c9",
    "emailVerified":false,
    "kA":"5e1994b0159081921adb416236058d92bd0715a91c884654e4269c49d467a160",
    "wrapWrapKb":"a746589a4d3db2b0552476bae4fc8c9156d29499eeb0d6583ffd6ddcd7482097",
    "authSalt":"d870b1472524fcef2cfd512533b1fb19fe6cf1b555cb5d85d60a636cc5356aba",
    "verifyHash":"5791981c2f0685aa9400597b6bee51d04c59399798e9bcf3cdbeec3d8b50971f",
    "verifierVersion":1,
    "verifierSetAt":1424993616858,
    "locale":"en_US",
    "createdAt":1424993616858,
    "devices":{}
}

Status Code : 200 OK
- Content-Type : 'application/json'
- Body : { ... <see example> ... }
Status Code : 404 Not Found
- Conditions: if this account uid or normalizedEmail already exists
- Content-Type : 'application/json'
- Body : {"message":"Not Found"}
Status Code : 500 Internal Server Error
- Conditions: if something goes wrong on the server
- Content-Type : 'application/json'
- Body : {"code":"InternalError","message":"...<message related to the error>..."}

accountExists : `HEAD /emailRecord/<email>`

Example

curl \
    -v \
    -X HEAD \
    http://localhost:8000/emailRecord/foo@example.com

Request

Method : HEAD
Path : /emailRecord/<email>
- email : string255
Params: none

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 564

Status Code : 200 OK
- Content-Type : 'application/json'
- Body : empty
Status Code : 404 Not Found
- Conditions: if this email does not exist
- Content-Type : 'application/json'
- Body : empty
Status Code : 500 Internal Server Error
- Conditions: if something goes wrong on the server
- Content-Type : 'application/json'
- Body : empty

emailRecord : `GET /emailRecord/<email>`

Similar to GET /account/<uid> but using email address instead of uid.

Example

curl \
    -v \
    -X GET \
    http://localhost:8000/emailRecord/foo@example.com

Request

Method : GET
Path : /emailRecord/<email>
- email : string255
Params: none

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 564

{
    "normalizedEmail":"foo@example.com",
    "email":"foo@example.com",
    "emailCode":"9b4da6ccd05e7c24ce6a6c0d208bc7c9",
    "emailVerified":false,
    "kA":"5e1994b0159081921adb416236058d92bd0715a91c884654e4269c49d467a160",
    "wrapWrapKb":"a746589a4d3db2b0552476bae4fc8c9156d29499eeb0d6583ffd6ddcd7482097",
    "authSalt":"d870b1472524fcef2cfd512533b1fb19fe6cf1b555cb5d85d60a636cc5356aba",
    "verifyHash":"5791981c2f0685aa9400597b6bee51d04c59399798e9bcf3cdbeec3d8b50971f",
    "verifierVersion":1,
    "verifierSetAt":1424993616858,
    "locale":"en_US",
    "createdAt":1424993616858,
    "devices":{}
}

Status Code : 200 OK
- Content-Type : 'application/json'
- Body : { ... <see example> ... }
Status Code : 404 Not Found
- Conditions: if this account uid or normalizedEmail already exists
- Content-Type : 'application/json'
- Body : {"message":"Not Found"}
Status Code : 500 Internal Server Error
- Conditions: if something goes wrong on the server
- Content-Type : 'application/json'
- Body : {"code":"InternalError","message":"...<message related to the error>..."}

checkPassword : `POST /account/<uid>/checkPassword`

Returns back the same uid if correct.

Example

curl \
    -v \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{
        "verifyHash":"5791981c2f0685aa9400597b6bee51d04c59399798e9bcf3cdbeec3d8b50971f"
    }' \
    http://localhost:8000/account/6044486dd15b42e08b1fb9167415b9ac/checkPassword

Request

Method : POST
Path : /account/<uid>/checkPassword
- verifyHash : hex256
Params: none

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 90

{
    "uid":"6044486dd15b42e08b1fb9167415b9ac"
}

Status Code : 200 OK
- Content-Type : 'application/json'
- Body : { ... <see example> ... }
Status Code : 400 Bad Request
- Conditions: if this account uid doesn't exist or the password is incorrect
- Content-Type : 'application/json'
- Body : {"message":"Incorrect password"}
Status Code : 500 Internal Server Error
- Conditions: if something goes wrong on the server
- Content-Type : 'application/json'
- Body : {"code":"InternalError","message":"...<message related to the error>..."}

resetAccount : `POST /account/<uid>/reset`

resetTokens : `POST /account/<uid>/resetTokens`

deleteAccount : `DELETE /account/<uid>`

verifyEmail : `POST /account/<uid>/verifyEmail`

curl \
    -v \
    -X POST \
    http://localhost:8000/account/6044486dd15b42e08b1fb9167415b9ac/verifyEmail

Request

Method : POST
Path : /account/<uid>/verifyEmail
- uid : hex128
Params: none

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2

{}

Status Code : 200 OK
- Content-Type : 'application/json'
- Body : {}
Status Code : 500 Internal Server Error
- Conditions: if something goes wrong on the server
- Content-Type : 'application/json'
- Body : {"code":"InternalError","message":"...<message related to the error>..."}

Note: if the account uid is not found, a 200 OK is returned anyway.

sessions : `GET /account/<uid>/sessions`

curl \
    -v \
    -X GET \
    http://localhost:8000/account/6044486dd15b42e08b1fb9167415b9ac/sessions

Request

Method : GET
Path : /account/<uid>/sessions
- uid : hex128
Params: none

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 371

[
    {
        "id":"522c251a1623e1f1db1f4fe68b9594d26772d6e77e04cb68e110c58600f97a77",
        "uid":"6044486dd15b42e08b1fb9167415b9ac",
        "createdAt":1425004396952,
        "uaBrowser":"Firefox",
        "uaBrowserVersion":"42",
        "uaOS":"Mac OS X",
        "uaOSVersion":"10.10",
        "uaDeviceType":null,
        "uaFormFactor":null,
        "lastAccessTime":1441874852627
    }
]

Status Code : 200 OK
- Content-Type : 'application/json'
- Body : [...]
Status Code : 500 Internal Server Error
- Conditions: if something goes wrong on the server
- Content-Type : 'application/json'
- Body : {"code":"InternalError","message":"...<message related to the error>..."}

Note: if the account uid is not found, the response is 200 OK with an empty array in the body.

createSessionToken : `PUT /sessionToken/<tokenId>`

Example

curl \
    -v \
    -X PUT \
    -H "Content-Type: application/json" \
    -d '{
        "uid" :  "6044486dd15b42e08b1fb9167415b9ac",
        "data" : "e2c3a8f73e826b9176e54e0f6ecb34b60b1e1979d254638f6b61d721c069d576",
        "createdAt" : 1425004396952,
        "uaBrowser" : Firefox,
        "uaBrowserVersion" : 47,
        "uaOS" : Mac OS X,
        "uaOSVersion" : 10.10,
        "uaDeviceType" : null,
        "uaFormFactor" : null,
        "mustVerify":true,
        "tokenVerificationId" : "5680a81ba029af7b829afb4aa6dbc23f"
    }' \
    http://localhost:8000/sessionToken/522c251a1623e1f1db1f4fe68b9594d26772d6e77e04cb68e110c58600f97a77

Request

Method : PUT
Path : /sessionToken/<tokenId>
- tokenId : hex256
Params:
- uid : hex128
- data : hex256
- createdAt : epoch
- uaBrowser : string
- uaBrowserVersion : string
- uaOS : string
- uaOSVersion : string
- uaDeviceType : string
- uaFormFactor : string
- mustVerify : boolean,
- tokenVerificationId : hex128

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2

{}

Status Code : 200 OK
- Content-Type : 'application/json'
- Body : {}
Status Code : 409 Conflict
- Conditions: if this tokenId already exists
- Content-Type : 'application/json'
- Body : {"message":"Record already exists"}
Status Code : 500 Internal Server Error
- Conditions: if something goes wrong on the server
- Content-Type : 'application/json'
- Body : {"code":"InternalError","message":"......"}

updateSessionToken : `POST /sessionToken/<tokenId>/update`

This updates the user agent and last-access time for a particular token.

Example

curl \
    -v \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{
        "uaBrowser" : "Firefox",
        "uaBrowserVersion" : "42",
        "usOS" : "Android",
        "usOSVersion" : "5.1",
        "uaDeviceType": "mobile",
        "lastAccessTime": 1437992394186
    }' \
    http://localhost:8000/sessionToken/522c251a1623e1f1db1f4fe68b9594d26772d6e77e04cb68e110c58600f97a77/update

Request

Method : POST
Path : /sessionToken/<tokenId>/update
- tokenId : hex256
Params:
- uaBrowser : string
- uaBrowserVersion : string
- uaOS : string
- uaOSVersion : string
- uaDeviceType : string
- lastAccessTime : epoch

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2

{}

Status Code : 200 OK
- Content-Type : 'application/json'
- Body : {}
Status Code : 404 Not Found
- Conditions: if this session tokenId doesn't exist
- Content-Type : 'application/json'
- Body : {"message":"Not Found"}
Status Code : 500 Internal Server Error
- Conditions: if something goes wrong on the server
- Content-Type : 'application/json'
- Body : {"code":"InternalError","message":"...<message related to the error>..."}

accountDevices : `GET /account/<uid>/devices`

Example

curl \
    -v \
    -X GET \
    http://localhost:8000/account/6044486dd15b42e08b1fb9167415b9ac/devices

Request

Method : GET
Path : /account/<uid>/devices
- uid : hex128
Params: none

Response

Note: The deviceCallbackPublicKey and deviceCallbackAuthKey fields are urlsafe-base64 strings, you can learn more about their format here.

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": "154c86dde08bfbb47415b9a216044916",
        "uid": "6044486dd15b42e08b1fb9167415b9ac",
        "sessionTokenId": "9a15b9ad6044ce08bfbb4744b1604491686dd15b42e2154c86d08b1fb9167415",
        "name": "My Phone",
        "type": "mobile"
        "createdAt": 1437992394186,
        "callbackURL": "https://updates.push.services.mozilla.com/update/abcdef01234567890abcdefabcdef01234567890abcdef",
        "callbackPublicKey": "BCp93zru09_hab2Bg37LpTNG__Pw6eMPEP2hrQpwuytoj3h4chXpGc-3qqdKyqjuvAiEupsnOd_RLyc7erJHWgA",
        "callbackAuthKey": "w3b14Zjc-Afj2SDOLOyong",
        "callbackIsExpired": false,
        "capabilities": ["messages"],
        "uaBrowser": "Firefox",
        "uaBrowserVersion": "42",
        "uaOS": "Android",
        "uaOSVersion": "5.1",
        "uaDeviceType": "mobile",
        "uaFormFactor": null,
        "lastAccessTime": 1437992394186,
        "email": "foo@example.org"
    }
]

Status Code : 200 OK
- Content-Type : 'application/json'
- Body : [ ... <see example> ...]
Status Code : 404 Not Found
- Conditions: if this account uid doesn't exist
- Content-Type : 'application/json'
- Body : {"message":"Not Found"}
Status Code : 500 Internal Server Error
- Conditions: if something goes wrong on the server
- Content-Type : 'application/json'
- Body : {"code":"InternalError","message":"...<message related to the error>..."}

deviceFromTokenVerificationId : `GET /account/<uid>/tokens/<tokenVerificationId>/device`

Example

curl \
    -v \
    -X GET \
    http://localhost:8000/account/6044486dd15b42e08b1fb9167415b9ac/tokens/12c41fac80fd6149f3f695e188b5f846/device

Request

Method : GET
Path : /account/<uid>/tokens/<tokenVerificationId>/device
- uid : hex128
- tokenVerificationId : hex128
Params: none

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "154c86dde08bfbb47415b9a216044916",
    "name": "My Phone",
    "type": "mobile"
    "createdAt": 1437992394186,
    "callbackURL": "https://updates.push.services.mozilla.com/update/abcdef01234567890abcdefabcdef01234567890abcdef",
    "callbackPublicKey": "BCp93zru09_hab2Bg37LpTNG__Pw6eMPEP2hrQpwuytoj3h4chXpGc-3qqdKyqjuvAiEupsnOd_RLyc7erJHWgA",
    "callbackAuthKey": "w3b14Zjc-Afj2SDOLOyong",
    "callbackIsExpired": false,
    "capabilities": ["messages"]
}

Status Code : 200 OK
- Content-Type : 'application/json'
- Body : [ ... <see example> ...]
Status Code : 404 Not Found
- Conditions: if the tokenVerificationId doesn't exist or if there is no device associated with it
- Content-Type : 'application/json'
- Body : {"message":"Not Found"}
Status Code : 500 Internal Server Error
- Conditions: if something goes wrong on the server
- Content-Type : 'application/json'
- Body : {"code":"InternalError","message":"...<message related to the error>..."}

createDevice : `PUT /account/<uid>/device/<deviceId>`

Example

curl \
    -v \
    -X PUT \
    http://localhost:8000/account/6044486dd15b42e08b1fb9167415b9ac/device/154c86dde08bfbb47415b9a216044916 \
    -d '{
      "id": "154c86dde08bfbb47415b9a216044916",
      "uid": "6044486dd15b42e08b1fb9167415b9ac",
      "sessionTokenId": "9a15b9ad6044ce08bfbb4744b1604491686dd15b42e2154c86d08b1fb9167415",
      "name": "My Phone",
      "type": "mobile"
      "createdAt": 1437992394186,
      "callbackURL": "https://updates.push.services.mozilla.com/update/abcdef01234567890abcdefabcdef01234567890abcdef",
      "callbackPublicKey": "BCp93zru09_hab2Bg37LpTNG__Pw6eMPEP2hrQpwuytoj3h4chXpGc-3qqdKyqjuvAiEupsnOd_RLyc7erJHWgA",
      "callbackAuthKey": "w3b14Zjc-Afj2SDOLOyong",
      "callbackIsExpired": false,
      "capabilities": ["messages"]
    }'

Response

HTTP/1.1 200 OK
Content-Type: application/json

{}

Status Code : 200 OK
- Content-Type : 'application/json'
- Body : [ ... <see example> ...]
Status Code : 409 Conflict
- Conditions: if id already exists or sessionTokenId is already used by a different device
- Content-Type : 'application/json'
- Body : {"errno":101",message":"Record already exists"}
Status Code : 400 Bad Request
- Conditions: if the device in the request body contained an unknown capability name
- Content-Type : 'application/json'
- Body : {"errno":139",message":"Unknown device capability"}
Status Code : 500 Internal Server Error
- Conditions: if something goes wrong on the server
- Content-Type : 'application/json'
- Body : {"code":"InternalError","message":"...<message related to the error>..."}

updateDevice : `POST /account/<uid>/device/<deviceId>/update`

Example

curl \
    -v \
    -X POST \
    http://localhost:8000/account/6044486dd15b42e08b1fb9167415b9ac/device/154c86dde08bfbb47415b9a216044916/update \
    -d '{
      "id": "154c86dde08bfbb47415b9a216044916",
      "uid": "6044486dd15b42e08b1fb9167415b9ac",
      "sessionTokenId": "9a15b9ad6044ce08bfbb4744b1604491686dd15b42e2154c86d08b1fb9167415",
      "name": "My Phone",
      "type": "mobile"
      "createdAt": 1437992394186,
      "callbackURL": "https://updates.push.services.mozilla.com/update/abcdef01234567890abcdefabcdef01234567890abcdef",
      "callbackPublicKey": "BCp93zru09_hab2Bg37LpTNG__Pw6eMPEP2hrQpwuytoj3h4chXpGc-3qqdKyqjuvAiEupsnOd_RLyc7erJHWgA",
      "callbackAuthKey": "w3b14Zjc-Afj2SDOLOyong",
      "callbackIsExpired": false,
      "capabilities": ["messages"]
    }'

Response

HTTP/1.1 200 OK
Content-Type: application/json

{}

Status Code : 200 OK
- Content-Type : 'application/json'
- Body : [ ... <see example> ...]
Status Code : 409 Conflict
- Conditions: if sessionTokenId is already used by a different device
- Content-Type : 'application/json'
- Body : {"errno":101",message":"Record already exists"}
Status Code : 400 Bad Request
- Conditions: if the device in the request body contained an unknown capability name
- Content-Type : 'application/json'
- Body : {"errno":139",message":"Unknown device capability"}
Status Code : 404 Not Found
- Conditions: if device(uid,id) is not found in the database
- Content-Type : 'application/json'
- Body : {"errno":116,"message":"Not found"}
Status Code : 500 Internal Server Error
- Conditions: if something goes wrong on the server
- Content-Type : 'application/json'
- Body : {"code":"InternalError","message":"...<message related to the error>..."}

deleteDevice : `DELETE /account/<uid>/device/<deviceId>`

Example

curl \
    -v \
    -X DELETE \
    http://localhost:8000/account/6044486dd15b42e08b1fb9167415b9ac/device/154c86dde08bfbb47415b9a216044916

Response

HTTP/1.1 200 OK
Content-Type: application/json

{"sessionTokenId":"522c251a1623e1f1db1f4fe68b9594d26772d6e77e04cb68e110c58600f97a77"}

Status Code : 200 OK
- Content-Type : 'application/json'
- Body : [ ... <see example> ...]
Status Code : 404 Not Found
- Conditions: if device(uid,id) is not found in the database
- Content-Type : 'application/json'
- Body : {"errno":116,"message":"Not found"}
Status Code : 500 Internal Server Error
- Conditions: if something goes wrong on the server
- Content-Type : 'application/json'
- Body : {"code":"InternalError","message":"...<message related to the error>..."}

sessionToken : `GET /sessionToken/<tokenId>`

Example

curl \
    -v \
    -X GET \
    http://localhost:8000/sessionToken/522c251a1623e1f1db1f4fe68b9594d26772d6e77e04cb68e110c58600f97a77

Request

Method : GET
Path : /sessionToken/<tokenId>
- tokenId : hex256
Params: none

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 285

{
    "data":"e2c3a8f73e826b9176e54e0f6ecb34b60b1e1979d254638f6b61d721c069d576",
    "uid":"6044486dd15b42e08b1fb9167415b9ac",
    "createdAt":1460548810011,
    "id":"522c251a1623e1f1db1f4fe68b9594d26772d6e77e04cb68e110c58600f97a77",
    "uaBrowser":"Firefox",
    "uaBrowserVersion":"47",
    "uaOS":"Mac OS X",
    "uaOSVersion":"10.10",
    "uaDeviceType":null,
    "uaFormFactor":null,
    "lastAccessTime":1460548810011
    "emailVerified":0,
    "email":"foo@example.com",
    "verifierSetAt":1460548810011,
    "locale":"en_US",
    "accountCreatedAt":1460548810011,
    "deviceId":"eb87eb63c2063bf5fd35e83b535c123d073db9156e49b58bcbf543f9d35467f6",
    "deviceName":"foo",
    "deviceType":"mobile",
    "deviceCreatedAt":1460548810011,
    "deviceCallbackURL":null,
    "deviceCallbackPublicKey":null,
    "deviceCallbackIsExpired":false,
    "deviceCapabilities":["messages"],
    "mustVerify":true,
    "tokenVerificationId":"12c41fac80fd6149f3f695e188b5f846"
}

Status Code : 200 OK
- Content-Type : 'application/json'
- Body : [ ... <see example> ...]
Status Code : 404 Not Found
- Conditions: if this session tokenId doesn't exist
- Content-Type : 'application/json'
- Body : {"message":"Not Found"}
Status Code : 500 Internal Server Error
- Conditions: if something goes wrong on the server
- Content-Type : 'application/json'
- Body : {"code":"InternalError","message":"...<message related to the error>..."}

deleteSessionToken : `DELETE /sessionToken/<tokenId>`

This operation is idempotent. If you delete a tokenId twice, the same result occurs. In fact, if you delete a tokenId that doesn't exist, it also returns the same 200 OK result (since it is already not there). Also deletes any device records associated with the session.

Example

curl \
    -v \
    -X DELETE \
    http://localhost:8000/sessionToken/522c251a1623e1f1db1f4fe68b9594d26772d6e77e04cb68e110c58600f97a77

Request

Method : DELETE
Path : /sessionToken/<tokenId>
- tokenId : hex256
Params: none

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2

{}

Status Code : 200 OK
- Content-Type : 'application/json'
- Body : [ ... <see example> ...]
Status Code : 404 Not Found
- Conditions: if this session tokenId doesn't exist
- Content-Type : 'application/json'
- Body : {"message":"Not Found"}
Status Code : 500 Internal Server Error
- Conditions: if something goes wrong on the server
- Content-Type : 'application/json'
- Body : {"code":"InternalError","message":"...<message related to the error>..."}

accountResetToken : `GET /accountResetToken/<tokenId>`

Example

curl \
    -v \
    -X GET \
    http://localhost:8000/accountResetToken/da7e3b59fc6021836ed205d2176c11819932c9554bec5a40a1f4178b7f08194d

Request

Method : GET
Path : /accountResetToken/<tokenId>
- tokenId : hex256
Params: none

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 177

{
    "tokenData":"b034061cc2886a3c3c08bd4e9bbc8afc4bc3fc9bca12d5b5d0aa7e0a7f78b9ce",
    "uid":"6044486dd15b42e08b1fb9167415b9ac",
    "createdAt":1425004396952,
    "verifierSetAt":1424993616858
}

Status Code : 200 OK
- Content-Type : 'application/json'
- Body : [ ... <see example> ...]
Status Code : 404 Not Found
- Conditions: if this session tokenId doesn't exist
- Content-Type : 'application/json'
- Body : {"message":"Not Found"}
Status Code : 500 Internal Server Error
- Conditions: if something goes wrong on the server
- Content-Type : 'application/json'
- Body : {"code":"InternalError","message":"...<message related to the error>..."}

deleteAccountResetToken : `DELETE /accountResetToken/<tokenId>`

This operation is idempotent. If you delete a tokenId twice, the same result occurs. In fact, if you delete a tokenId that doesn't exist, it also returns the same 200 OK result (since it is already not there).

Example

curl \
    -v \
    -X DELETE \
    http://localhost:8000/accountResetToken/da7e3b59fc6021836ed205d2176c11819932c9554bec5a40a1f4178b7f08194d

Request

Method : DELETE
Path : /accountResetToken/<tokenId>
- tokenId : hex256
Params: none

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2

{}

Status Code : 200 OK
- Content-Type : 'application/json'
- Body : {}
Status Code : 500 Internal Server Error
- Conditions: if something goes wrong on the server
- Content-Type : 'application/json'
- Body : {"code":"InternalError","message":"...<message related to the error>..."}

createKeyFetchToken : `PUT /keyFetchToken/<tokenId>`

Example

curl \
    -v \
    -X PUT \
    -H "Content-Type: application/json" \
    -d '{
        "uid"       : "6044486dd15b42e08b1fb9167415b9ac",
        "authKey"   : "b034061cc2886a3c3c08bd4e9bbc8afc4bc3fc9bca12d5b5d0aa7e0a7f78b9ce",
        "keyBundle" : "83333269c64eb43219f8b5807d37ac2391fc77295562685a5239674e2b0215920c45e2295c0d92fa7d69cb58d1e3c6010e1281f6d6c0df694b134815358110ae22a7b4c348a4f426bef3783b0493b3a531b649c0e2f19848d9563a61cd0f7eb8",
        "createdAt" : 1425004396952,
        "tokenVerificationId" : "a6062c21560edad350e6a654bdd9fd4f"
    }' \
    http://localhost:8000/keyFetchToken/4c17443c1bcf5e509bc90904905ea1974900120d3dd34e7061f182cb063f976a

Request

Method : PUT
Path : /keyFetchToken/<tokenId>
- tokenId : hex256
Params:
- uid : hex128
- authKey : hex256
- keyBundle : hex768
- createdAt : epoch
- tokenVerificationId : hex128

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2

{}

Status Code : 200 OK
- Content-Type : 'application/json'
- Body : {}
Status Code : 409 Conflict
- Conditions: if this tokenId already exists
- Content-Type : 'application/json'
- Body : {"message":"Record already exists"}
Status Code : 500 Internal Server Error
- Conditions: if something goes wrong on the server
- Content-Type : 'application/json'
- Body : {"code":"InternalError","message":"......"}


## keyFetchToken : `GET /keyFetchToken/<tokenId>`

### Example

curl
-v
-X GET
http://localhost:8000/keyFetchToken/4c17443c1bcf5e509bc90904905ea1974900120d3dd34e7061f182cb063f976a


### Request

* Method : GET
* Path : `/keyFetchToken/<tokenId>`
    * tokenId : hex256
* Params: none

### Response

HTTP/1.1 200 OK Content-Type: application/json Content-Length: 399

{ "authKey":"b034061cc2886a3c3c08bd4e9bbc8afc4bc3fc9bca12d5b5d0aa7e0a7f78b9ce", "uid":"6044486dd15b42e08b1fb9167415b9ac", "keyBundle":"83333269c64eb43219f8b5807d37ac2391fc77295562685a5239674e2b0215920c45e2295c0d92fa7d69cb58d1e3c6010e1281f6d6c0df694b134815358110ae22a7b4c348a4f426bef3783b0493b3a531b649c0e2f19848d9563a61cd0f7eb8", "createdAt":1425004396952, "emailVerified":false, "verifierSetAt":1425263030609 }


* Status Code : 200 OK
    * Content-Type : 'application/json'
    * Body : `[ ... <see example> ...]`
* Status Code : 404 Not Found
    * Conditions: if this session `tokenId` doesn't exist
    * Content-Type : 'application/json'
    * Body : `{"message":"Not Found"}`
* Status Code : 500 Internal Server Error
    * Conditions: if something goes wrong on the server
    * Content-Type : 'application/json'
    * Body : `{"code":"InternalError","message":"...<message related to the error>..."}`

## keyFetchTokenWithVerificationStatus : `GET /keyFetchToken/<tokenId>/verified`

### Example

curl
-v
-X GET
http://localhost:8000/keyFetchToken/4c17443c1bcf5e509bc90904905ea1974900120d3dd34e7061f182cb063f976a/verified


### Request

* Method : GET
* Path : `/keyFetchToken/<tokenId>/verified`
    * tokenId : hex256
* Params: none

### Response

HTTP/1.1 200 OK Content-Type: application/json Content-Length: 399

{ "authKey":"b034061cc2886a3c3c08bd4e9bbc8afc4bc3fc9bca12d5b5d0aa7e0a7f78b9ce", "uid":"6044486dd15b42e08b1fb9167415b9ac", "keyBundle":"83333269c64eb43219f8b5807d37ac2391fc77295562685a5239674e2b0215920c45e2295c0d92fa7d69cb58d1e3c6010e1281f6d6c0df694b134815358110ae22a7b4c348a4f426bef3783b0493b3a531b649c0e2f19848d9563a61cd0f7eb8", "createdAt":1460548810011, "emailVerified":0, "verifierSetAt":1460548810011, "tokenVerificationId":"12c41fac80fd6149f3f695e188b5f846" }


* Status Code : 200 OK
    * Content-Type : 'application/json'
    * Body : `[ ... <see example> ...]`
* Status Code : 404 Not Found
    * Conditions: if the keyFetchToken `tokenId` doesn't exist
    * Content-Type : 'application/json'
    * Body : `{"message":"Not Found"}`
* Status Code : 500 Internal Server Error
    * Conditions: if something goes wrong on the server
    * Content-Type : 'application/json'
    * Body : `{"code":"InternalError","message":"...<message related to the error>..."}`

## deleteKeyFetchToken : `DELETE /keyFetchToken/<tokenId>`

This operation is idempotent. If you delete a `tokenId` twice, the same result occurs. In fact, if you delete a
`tokenId` that doesn't exist, it also returns the same `200 OK` result (since it is already not there).

### Example

curl
-v
-X DELETE
http://localhost:8000/keyFetchToken/4c17443c1bcf5e509bc90904905ea1974900120d3dd34e7061f182cb063f976a


### Request

* Method : DELETE
* Path : `/keyFetchToken/<tokenId>`
    * tokenId : hex256
* Params: none

### Response

HTTP/1.1 200 OK Content-Type: application/json Content-Length: 2

{}


* Status Code : 200 OK
    * Content-Type : 'application/json'
    * Body : `{}`
* Status Code : 500 Internal Server Error
    * Conditions: if something goes wrong on the server
    * Content-Type : 'application/json'
    * Body : `{"code":"InternalError","message":"...<message related to the error>..."}`


## createPasswordChangeToken : `PUT /passwordChangeToken/<tokenId>`

### Example

curl
-v
-X PUT
-H "Content-Type: application/json"
-d '{ "uid" : "6044486dd15b42e08b1fb9167415b9ac", "data" : "bbfe036d84cc1ae9b5eecc503ff9106c61d25961d5680669d2065c6bb7a5530d", "createdAt" : 1425004396952 }'
http://localhost:8000/passwordChangeToken/20f751b2cc61129d9bc631d70c994129a35da6bf324456e4bdb82a0381ca76ec


### Request

* Method : PUT
* Path : `/passwordChangeToken/<tokenId>`
    * tokenId : hex256
* Params:
    * uid : hex128
    * data : hex256
    * createdAt : epoch

### Response

HTTP/1.1 200 OK Content-Type: application/json Content-Length: 2

{}


* Status Code : 200 OK
    * Content-Type : 'application/json'
    * Body : {}
* Status Code : 409 Conflict
    * Conditions: if this `tokenId` already exists
    * Content-Type : 'application/json'
    * Body : {"message":"Record already exists"}
* Status Code : 500 Internal Server Error
    * Conditions: if something goes wrong on the server
    * Content-Type : 'application/json'
    * Body : {"code":"InternalError","message":"...<message related to the error>..."}

passwordChangeToken : `GET /passwordChangeToken/<tokenId>`

Example

curl \
    -v \
    -X GET \
    http://localhost:8000/passwordChangeToken/20f751b2cc61129d9bc631d70c994129a35da6bf324456e4bdb82a0381ca76ec

Request

Method : GET
Path : /passwordChangeToken/<tokenId>
- tokenId : hex256
Params: none

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 177

{
    "tokenData":"bbfe036d84cc1ae9b5eecc503ff9106c61d25961d5680669d2065c6bb7a5530d",
    "uid":"6044486dd15b42e08b1fb9167415b9ac",
    "createdAt":1425004396952,
    "verifierSetAt":1425263030609
}

Status Code : 200 OK
- Content-Type : 'application/json'
- Body : [ ... <see example> ...]
Status Code : 404 Not Found
- Conditions: if this session tokenId doesn't exist
- Content-Type : 'application/json'
- Body : {"message":"Not Found"}
Status Code : 500 Internal Server Error
- Conditions: if something goes wrong on the server
- Content-Type : 'application/json'
- Body : {"code":"InternalError","message":"...<message related to the error>..."}

deletePasswordChangeToken : `DELETE /passwordChangeToken/<tokenId>`

This operation is idempotent. If you delete a tokenId twice, the same result occurs. In fact, if you delete a tokenId that doesn't exist, it also returns the same 200 OK result (since it is already not there).

Example

curl \
    -v \
    -X DELETE \
    http://localhost:8000/passwordChangeToken/20f751b2cc61129d9bc631d70c994129a35da6bf324456e4bdb82a0381ca76ec

Request

Method : DELETE
Path : /passwordChangeToken/<tokenId>
- tokenId : hex256
Params: none

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2

{}

Status Code : 200 OK
- Content-Type : 'application/json'
- Body : {}
Status Code : 500 Internal Server Error
- Conditions: if something goes wrong on the server
- Content-Type : 'application/json'
- Body : {"code":"InternalError","message":"...<message related to the error>..."}

createPasswordForgotToken : `PUT /passwordForgotToken/<tokenId>`

Example

curl \
    -v \
    -X PUT \
    -H "Content-Type: application/json" \
    -d '{
        "uid"       : "6044486dd15b42e08b1fb9167415b9ac",
        "data"      : "958266599bdc7218277a349f2675ebf38d8542eb784e01d1332f87fb98a970c3",
        "passCode"  : "95c0fab6a666b1a5cbf2db4700a6a779",
        "tries"     : 1,
        "createdAt" : 1425004396952
    }' \
    http://localhost:8000/passwordForgotToken/266fd690895c8b0086bb2c83e4b3b41c128746125f28b5429938765279673d62

Request

Method : PUT
Path : /passwordForgotToken/<tokenId>
- tokenId : hex256
Params:
- uid : hex128
- data : hex256
- passCode : hex128
- tries : int
- createdAt : epoch

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2

{}

Status Code : 200 OK
- Content-Type : 'application/json'
- Body : {}
Status Code : 409 Conflict
- Conditions: if this tokenId already exists
- Content-Type : 'application/json'
- Body : {"message":"Record already exists"}
Status Code : 500 Internal Server Error
- Conditions: if something goes wrong on the server
- Content-Type : 'application/json'
- Body : {"code":"InternalError","message":"......"}


## passwordForgotToken : `GET /passwordForgotToken/<tokenId>`

### Example

curl
-v
-X GET
http://localhost:8000/passwordForgotToken/266fd690895c8b0086bb2c83e4b3b41c128746125f28b5429938765279673d62


### Request

* Method : GET
* Path : `/passwordChangeToken/<tokenId>`
    * tokenId : hex256
* Params: none

### Response

HTTP/1.1 200 OK Content-Type: application/json Content-Length: 259

{ "tokenData":"958266599bdc7218277a349f2675ebf38d8542eb784e01d1332f87fb98a970c3", "uid":"6044486dd15b42e08b1fb9167415b9ac", "passCode":"95c0fab6a666b1a5cbf2db4700a6a779", "tries":1, "createdAt":1425004396952, "email":"foo@example.com", "verifierSetAt":1425263030609 }


* Status Code : 200 OK
    * Content-Type : 'application/json'
    * Body : `[ ... <see example> ...]`
* Status Code : 404 Not Found
    * Conditions: if this session `tokenId` doesn't exist
    * Content-Type : 'application/json'
    * Body : `{"message":"Not Found"}`
* Status Code : 500 Internal Server Error
    * Conditions: if something goes wrong on the server
    * Content-Type : 'application/json'
    * Body : `{"code":"InternalError","message":"...<message related to the error>..."}`

## deletePasswordForgotToken : `DELETE /passwordForgotToken/<tokenId>`

This operation is idempotent. If you delete a `tokenId` twice, the same result occurs. In fact, if you delete a
`tokenId` that doesn't exist, it also returns the same `200 OK` result (since it is already not there).

### Example

curl
-v
-X DELETE
http://localhost:8000/passwordForgotToken/266fd690895c8b0086bb2c83e4b3b41c128746125f28b5429938765279673d62


### Request

* Method : DELETE
* Path : `/passwordForgotToken/<tokenId>`
    * tokenId : hex256
* Params: none

### Response

HTTP/1.1 200 OK Content-Type: application/json Content-Length: 2

{}


* Status Code : 200 OK
    * Content-Type : 'application/json'
    * Body : `{}`
* Status Code : 500 Internal Server Error
    * Conditions: if something goes wrong on the server
    * Content-Type : 'application/json'
    * Body : `{"code":"InternalError","message":"...<message related to the error>..."}`


## updatePasswordForgotToken : `POST /passwordForgotToken/<tokenId>/update`

This just updates the number of tries for a particular token.

### Example

curl
-v
-X POST
-H "Content-Type: application/json"
-d '{ "tries" : 2 }'
http://localhost:8000/passwordForgotToken/266fd690895c8b0086bb2c83e4b3b41c128746125f28b5429938765279673d62/update


### Request

* Method : POST
* Path : `/passwordForgotToken/<tokenId>/update`
    * tokenId : hex256
* Params:
    * tries : int

### Response

HTTP/1.1 200 OK Content-Type: application/json Content-Length: 2

{}


* Status Code : 200 OK
    * Content-Type : 'application/json'
    * Body : {}
* Status Code : 404 Not Found
    * Conditions: if this session `tokenId` doesn't exist
    * Content-Type : 'application/json'
    * Body : `{"message":"Not Found"}`
* Status Code : 500 Internal Server Error
    * Conditions: if something goes wrong on the server
    * Content-Type : 'application/json'
    * Body : {"code":"InternalError","message":"...<message related to the error>..."}

forgotPasswordVerified : `POST /passwordForgotToken/<tokenId>/verified`

This method should:

delete the passwordForgotToken designated by
create a new accountResetToken as given in JSON
verify the email address for this account

Example

This request sends a new accountResetToken and receives back

curl \
    -v \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{
        "uid" :  "6044486dd15b42e08b1fb9167415b9ac",
        "data" : "cad0306bd6505df67d5fff2264e59a9eabdbfd4e441ac2272bda2d1e8c740072",
        "createdAt" : 1425004396952
    }' \
    http://localhost:8000/passwordForgotToken/266fd690895c8b0086bb2c83e4b3b41c128746125f28b5429938765279673d62/verified

Request

Method : PUT
Path : /passwordForgotToken/<tokenId>/update
- tokenId : hex256
Params:
- tries : int

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2

{}

Status Code : 200 OK
- Content-Type : 'application/json'
- Body : {}
Status Code : 404 Not Found
- Conditions: if this session tokenId doesn't exist
- Content-Type : 'application/json'
- Body : {"message":"Not Found"}
Status Code : 500 Internal Server Error
- Conditions: if something goes wrong on the server
- Content-Type : 'application/json'
- Body : {"code":"InternalError","message":"......"}


## verifyTokens : `POST /tokens/<tokenVerificationId>/verify`

This method verifies sessionTokens and keyFetchTokens.
Note that it takes the tokenVerificationId
specified when creating the token,
NOT the tokenId.

### Example

curl
-v
-X POST
-H "Content-Type: application/json"
-d '{"uid":"fdea27c8188b3d980a28917bc1399e47"}'
http://localhost:8000/tokens/8e8c27b704dbf6a5dc556453c92e7506/verify


### Request

* Method : POST
* Path : `/tokens/<tokenVerificationId>/verify`
    * tokenVerificationId : hex128
* Params:
    * uid : hex128

### Response

HTTP/1.1 200 OK Content-Type: application/json Content-Length: 2

{}


* Status Code : 200 OK
    * Content-Type : 'application/json'
    * Body : {}
* Status Code : 404 Not Found
    * Conditions: if no unverified tokens exist for `tokenVerificationId` and `uid`
    * Content-Type : 'application/json'
    * Body : `{"message":"Not Found"}`
* Status Code : 500 Internal Server Error
    * Conditions: if something goes wrong on the server
    * Content-Type : 'application/json'
    * Body : {"code":"InternalError","message":"...<message related to the error>..."}

verifyTokens : `POST /tokens/<tokenId>/verifyWithMethod`

This method verifies sessionTokens, keyFetchTokens and sets the the verification method used on the sessions table.

Example

curl \
    -v \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{"verificatioMethod":"totp-2fa"}' \
    http://localhost:8000/tokens/8e8c27b704dbf6a5dc556453c92e7506/verifyWithMethod

Request

Method : POST
Path : /tokens/<tokenId>/verifyWithMethod
- tokenVerificationId : hex128
Params:
- uid : hex128

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2

{}

Status Code : 200 OK
- Content-Type : 'application/json'
- Body : {}
Status Code : 404 Not Found
- Conditions: if no unverified tokens exist for tokenId
- Content-Type : 'application/json'
- Body : {"message":"Not Found"}
Status Code : 500 Internal Server Error
- Conditions: if something goes wrong on the server
- Content-Type : 'application/json'
- Body : {"code":"InternalError","message":"......"}


## createSigninCode : `PUT /signinCodes/:code`

Create a user-specific, time-limited, single-use code
that can be used for expedited sign-in.

### Example

curl
-v
-X PUT
-H "Content-Type: application/json"
-d '{"uid":"fdea27c8188b3d980a28917bc1399e47","createdAt":1494253830983,"flowId":"e04c12c6c97d8b61f0874f5ddd3447fa7a6e89459f0878746e6f2e6aa846345a"}'
http://localhost:8000/signinCodes/1234567890ab


### Request

* Method : `PUT`
* Path : `/signinCodes/<code>
    * `code` : hex
* Params:
    * `uid` : hex128
    * `createdAt` : epoch
    * `flowId` : hex256

### Response

HTTP/1.1 200 OK Content-Type: application/json Content-Length: 2

{}


* Status Code : `200 OK`
    * Content-Type : `application/json`
    * Body : `{}`
* Status Code : `409 Conflict`
    * Conditions: if the specified sign-in code already exists
    * Content-Type : `application/json`
    * Body : `{"errno":101,"message":"Record already exists"}`
* Status Code : `500 Internal Server Error`
    * Conditions: if something goes wrong on the server
    * Content-Type : `application/json`
    * Body : `{"code":"InternalError","message":"..."}`

## consumeSigninCode : `POST /signinCodes/:code/consume`

Use (and delete) a sign-in code.

### Example

curl
-v
-X POST
http://localhost:8000/signinCodes/1234567890ab/consume


### Request

* Method : `POST`
* Path : `/signinCodes/<code>/consume`
    * `code` : hex

### Response

HTTP/1.1 200 OK Content-Type: application/json Content-Length: 2

{"email":"foo@example.com","flowId":"e04c12c6c97d8b61f0874f5ddd3447fa7a6e89459f0878746e6f2e6aa846345a"}


* Status Code : `200 OK`
    * Content-Type : `application/json`
    * Body : `{"email":"foo@example.com","flowId":"e04c12c6c97d8b61f0874f5ddd3447fa7a6e89459f0878746e6f2e6aa846345a"}`
* Status Code : 404 Not Found
    * Conditions: if the specified sign-in code doesn't exist
    * Content-Type : `application/json`
    * Body : `{"errno":116,"message":"Not found"}`
* Status Code : `500 Internal Server Error`
    * Conditions: if something goes wrong on the server
    * Content-Type : `application/json`
    * Body : `{"code":"InternalError","message":"..."}`

## createTotpToken : `PUT /totp/:uid`

Used to create a TOTP token for a user.

### Example

curl
-v
-X PUT
-H "Content-Type: application/json"
-d '{"sharedSecret": "LEVXGTLWMFITC6BSIF2DOQKTIU2WUOKJ", "epoch": 0}'
http://localhost:8000/totp/1234567890ab


### Request

* Method : `PUT`
* Path : `/totp/<uid>
    * `uid` : hex
* Params:
    * `sharedSecret` : hex10
    * `epoch` : epoch

### Response

HTTP/1.1 200 OK Content-Type: application/json Content-Length: 2

{}


* Status Code : `200 OK`
    * Content-Type : `application/json`
    * Body : `{}`
* Status Code : `409 Conflict`
    * Conditions: if the user already has a TOTP device
    * Content-Type : `application/json`
    * Body : `{"errno":101,"message":"Record already exists"}`
* Status Code : `500 Internal Server Error`
    * Conditions: if something goes wrong on the server
    * Content-Type : `application/json`
    * Body : `{"code":"InternalError","message":"..."}`

## totpToken : `GET /totp/:uid`

Get the user's TOTP token.

### Example

curl
-v
-X GET
-H "Content-Type: application/json"
http://localhost:8000/totp/1234567890ab


### Request

* Method : `GET`
* Path : `/totp/<uid>`
    * `uid` : hex

### Response

HTTP/1.1 200 OK Content-Type: application/json Content-Length: 2

{ "sharedSecret": "LEVXGTLWMFITC6BSIF2DOQKTIU2WUOKJ", "epoch": 0, "verified": true, "enable": true }


* Status Code : `200 OK`
    * Content-Type : `application/json`
    * Body : `{"sharedSecret": "LEVXGTLWMFITC6BSIF2DOQKTIU2WUOKJ", "epoch": 0}`
* Status Code : `404 Not Found`
    * Conditions: if no TOTP token found for user
    * Content-Type : `application/json`
* Status Code : `500 Internal Server Error`
    * Conditions: if something goes wrong on the server
    * Content-Type : `application/json`
    * Body : `{"code":"InternalError","message":"..."}`

## deleteTotpToken : `DEL /totp/:uid`

Delete the user's TOTP token.

### Example

curl
-v
-X DEL
-H "Content-Type: application/json"
http://localhost:8000/totp/1234567890ab


### Request

* Method : `DEL`
* Path : `/totp/<uid>`
    * `uid` : hex

### Response

HTTP/1.1 200 OK Content-Type: application/json Content-Length: 2

{}


* Status Code : `200 OK`
    * Content-Type : `application/json`
    * Body : `{}`
* Status Code : `500 Internal Server Error`
    * Conditions: if something goes wrong on the server
    * Content-Type : `application/json`
    * Body : `{"code":"InternalError","message":"..."}`

## updateTotpToken : `POST /totp/:uid/update`

Updates the user's TOTP token.

### Example

curl
-v
-X DEL
-H "Content-Type: application/json"
-d '{ "verified" : true, "enable": true }'
http://localhost:8000/totp/1234567890ab/update


### Request

* Method : `POST`
* Path : `/totp/<uid>/update`
    * `uid` : hex

### Response

HTTP/1.1 200 OK Content-Type: application/json Content-Length: 2

{}


* Status Code : `200 OK`
    * Content-Type : `application/json`
    * Body : `{}`
* Status Code : `500 Internal Server Error`
    * Conditions: if something goes wrong on the server
    * Content-Type : `application/json`
    * Body : `{"code":"InternalError","message":"..."}`

## replaceRecoveryCodes : `GET /account/:uid/recoveryCodes`

Replaces a users current recovery codes with new ones.

### Example

curl
-v
-X POST
-H "Content-Type: application/json"
-d '{ "count" : 8 }' http://localhost:8000/account/1234567890ab/recoveryCodes


### Request

* Method : `POST`
* Path : `/account/<uid>/recoveryCodes`
    * `uid` : hex
*

### Response

HTTP/1.1 200 OK Content-Type: application/json Content-Length: 2

["code1", "code2"]


* Status Code : `200 OK`
    * Content-Type : `application/json`
    * Body : `["code1", "code2"]`
* Status Code : `404 Not Found`
    * Conditions: if no user found
    * Content-Type : `application/json`
* Status Code : `500 Internal Server Error`
    * Conditions: if something goes wrong on the server
    * Content-Type : `application/json`
    * Body : `{"code":"InternalError","message":"..."}`

## consumeRecoveryCode : `POST /account/:uid/recoveryCodes/:code`

Consumes a recovery code.

### Example

curl
-v
-X POST
-H "Content-Type: application/json"
http://localhost:8000/account/1234567890ab/recoveryCodes/1123


### Request

* Method : `POST`
* Path : `/account/<uid>/recoveryCodes/<code>`
    * `uid` : hex
    * `code`: hex

### Response

HTTP/1.1 200 OK Content-Type: application/json Content-Length: 2

{"remaining" : 1}


* Status Code : `200 OK`
    * Content-Type : `application/json`
    * Body : `{"remaining" : 1}`
* Status Code : `404 Not Found`
    * Conditions: if no user found or code not found
    * Content-Type : `application/json`
* Status Code : `500 Internal Server Error`
    * Conditions: if something goes wrong on the server
    * Content-Type : `application/json`
    * Body : `{"code":"InternalError","message":"..."}`

## createRecoveryKey : `POST /account/:uid/recoveryKeys`

Creates a new recovery key for the user.

### Example

curl
-v
-X POST
-H "Content-Type: application/json"
http://localhost:8000/account/1234567890ab/recoveryKeys


### Request

* Method : `POST`
* Path : `/account/<uid>/recoveryKeys`
    * `uid` : hex
    * `recoveryKeyId`: hex
    * `recoveryKeyData`: hex

### Response

HTTP/1.1 200 OK Content-Type: application/json Content-Length: 2

{}


* Status Code : `200 OK`
    * Content-Type : `application/json`
    * Body : `{}`
* Status Code : `500 Internal Server Error`
    * Conditions: if something goes wrong on the server
    * Content-Type : `application/json`
    * Body : `{"code":"InternalError","message":"..."}`

## getRecoveryKey : `GET /account/:uid/recoveryKey`

Returns recovery key data for a user.

### Example

curl
-v
-X GET
-H "Content-Type: application/json"
http://localhost:8000/account/1234567890ab/recoveryKey


### Request

* Method : `GET`
* Path : `/account/<uid>/recoveryKey`
    * `uid` : hex

### Response

HTTP/1.1 200 OK Content-Type: application/json Content-Length: 2

{ "recoveryKeyId": "6aa248931704886f54ac64b81b111bc0", "recoveryData": "eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIiwia2lkIjoiNmFhMjQ4OTMxNzA0ODg2ZjU0YWM2NGI4MWIxMTFiYzAifQ" }


* Status Code : `200 OK`
    * Content-Type : `application/json`
    * Body : `{}`
      * `recoveryKeyId`
      * `recoveryData`
* Status Code : `500 Internal Server Error`
    * Conditions: if something goes wrong on the server
    * Content-Type : `application/json`
    * Body : `{"code":"InternalError","message":"..."}`

## deleteRecoveryKey : `DELETE /account/:uid/recoveryKey`

Delete a user's recovery data.

### Example

curl
-v
-X DELETE
-H "Content-Type: application/json"
http://localhost:8000/account/1234567890ab/recoveryKey


### Request

* Method : `DELETE`
* Path : `/account/<uid>/recoveryKey`
    * `uid` : hex

### Response

HTTP/1.1 200 OK Content-Type: application/json Content-Length: 2

{}


* Status Code : `200 OK`
    * Content-Type : `application/json`
    * Body : `{}`
* Status Code : `500 Internal Server Error`
    * Conditions: if something goes wrong on the server
    * Content-Type : `application/json`
    * Body : `{"code":"InternalError","message":"..."}`

## recoveryKeyExists : `GET /account/:uid/recoveryKey`

Check if this user has a recovery key

### Example

curl
-v
-X GET
-H "Content-Type: application/json"
http://localhost:8000/account/1234567890ab/recoveryKey


### Request

* Method : `GET`
* Path : `/account/<uid>/recoveryKey`
    * `uid` : hex

### Response

HTTP/1.1 200 OK Content-Type: application/json Content-Length: 2

{"exists": true}


* Status Code : `200 OK`
    * Content-Type : `application/json`
    * Body : `{"exists": true}`
* Status Code : `500 Internal Server Error`
    * Conditions: if something goes wrong on the server
    * Content-Type : `application/json`
    * Body : `{"code":"InternalError","message":"..."}`

Files

API.md

Latest commit

History

API.md

File metadata and controls

Server API

Overview

URL Structure

Request Format

Response Format

Data Types

Operations

Operations

Ping : GET /

Request

Response

Heartbeat : GET /__heartbeat__

Request

Response

createAccount : PUT /account/<uid>

Example

Request

Response

GET /account/

Example

Request

Response

accountExists : HEAD /emailRecord/<email>

Example

Request

Response

emailRecord : GET /emailRecord/<email>

Example

Request

Response

checkPassword : POST /account/<uid>/checkPassword

Example

Request

Response

resetAccount : POST /account/<uid>/reset

resetTokens : POST /account/<uid>/resetTokens

deleteAccount : DELETE /account/<uid>

verifyEmail : POST /account/<uid>/verifyEmail

Request

Response

sessions : GET /account/<uid>/sessions

Request

Response

createSessionToken : PUT /sessionToken/<tokenId>

Example

Request

Response

updateSessionToken : POST /sessionToken/<tokenId>/update

Example

Request

Response

accountDevices : GET /account/<uid>/devices

Example

Request

Response

deviceFromTokenVerificationId : GET /account/<uid>/tokens/<tokenVerificationId>/device

Example

Request

Response

createDevice : PUT /account/<uid>/device/<deviceId>

Example

Response

updateDevice : POST /account/<uid>/device/<deviceId>/update

Example

Response

deleteDevice : DELETE /account/<uid>/device/<deviceId>

Example

Response

sessionToken : GET /sessionToken/<tokenId>

Example

Request

Response

deleteSessionToken : DELETE /sessionToken/<tokenId>

Example

Ping : `GET /`

Heartbeat : `GET /heartbeat`

createAccount : `PUT /account/<uid>`

accountExists : `HEAD /emailRecord/<email>`

emailRecord : `GET /emailRecord/<email>`

checkPassword : `POST /account/<uid>/checkPassword`

resetAccount : `POST /account/<uid>/reset`

resetTokens : `POST /account/<uid>/resetTokens`

deleteAccount : `DELETE /account/<uid>`

verifyEmail : `POST /account/<uid>/verifyEmail`

sessions : `GET /account/<uid>/sessions`

createSessionToken : `PUT /sessionToken/<tokenId>`

updateSessionToken : `POST /sessionToken/<tokenId>/update`

accountDevices : `GET /account/<uid>/devices`

deviceFromTokenVerificationId : `GET /account/<uid>/tokens/<tokenVerificationId>/device`

createDevice : `PUT /account/<uid>/device/<deviceId>`

updateDevice : `POST /account/<uid>/device/<deviceId>/update`

deleteDevice : `DELETE /account/<uid>/device/<deviceId>`

sessionToken : `GET /sessionToken/<tokenId>`

deleteSessionToken : `DELETE /sessionToken/<tokenId>`

accountResetToken : `GET /accountResetToken/<tokenId>`

deleteAccountResetToken : `DELETE /accountResetToken/<tokenId>`

createKeyFetchToken : `PUT /keyFetchToken/<tokenId>`

passwordChangeToken : `GET /passwordChangeToken/<tokenId>`

deletePasswordChangeToken : `DELETE /passwordChangeToken/<tokenId>`

createPasswordForgotToken : `PUT /passwordForgotToken/<tokenId>`

forgotPasswordVerified : `POST /passwordForgotToken/<tokenId>/verified`

verifyTokens : `POST /tokens/<tokenId>/verifyWithMethod`