Skip to content

Latest commit

 

History

History
1673 lines (1321 loc) · 41.7 KB

API.md

File metadata and controls

1673 lines (1321 loc) · 41.7 KB
Raw

Server API

The fxa-auth-db-server 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)
  • string255 : a string up to 255 characters/bytes long

Operations

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
    • deleteAccount : DELETE /account/:id
    • verifyEmail : POST /account/:id/verifyEmail
    • sessions : GET /account/:id/sessions
    • devices : GET /account/:id/devices
  • Devices:
    • createDevice : PUT /account/:id/device/:deviceId
    • updateDevice : POST /account/:id/device/:deviceId/update
    • deleteDevice : DEL /account/:id/device/:deviceId
  • Session Tokens:
    • sessionToken : GET /sessionToken/:id
    • deleteSessionToken : DEL /sessionToken/:id
    • createSessionToken : PUT /sessionToken/:id
    • updateSessionToken : POST /sessionToken/:id/update
  • Account Reset Tokens:
    • accountResetToken : GET /accountResetToken/:id
    • deleteAccountResetToken : DEL /accountResetToken/:id
    • createAccountResetToken : PUT /accountResetToken/:id
  • Key Fetch Tokens:
    • keyFetchToken : GET /keyFetchToken/:id
    • deleteKeyFetchToken : DEL /keyFetchToken/:id
    • createKeyFetchToken : PUT /keyFetchToken/:id
  • Password Change Tokens:
    • passwordChangeToken : GET /passwordChangeToken/:id
    • deletePasswordChangeToken : DEL /passwordChangeToken/:id
    • createPasswordChangeToken : PUT /passwordChangeToken/:id
  • Password Forgot Tokens:
    • passwordForgotToken : GET /passwordForgotToken/:id
    • deletePasswordForgotToken : DEL /passwordForgotToken/:id
    • createPasswordForgotToken : PUT /passwordForgotToken/:id
    • updatePasswordForgotToken : POST /passwordForgotToken/:id/update
    • forgotPasswordVerified : POST /passwordForgotToken/:id/verified

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" : "[email protected]",
        "email"           : "[email protected]",
        "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":"[email protected]",
    "email":"[email protected]",
    "emailCode":"9b4da6ccd05e7c24ce6a6c0d208bc7c9",
    "emailVerified":false,
    "kA":"5e1994b0159081921adb416236058d92bd0715a91c884654e4269c49d467a160",
    "wrapWrapKb":"a746589a4d3db2b0552476bae4fc8c9156d29499eeb0d6583ffd6ddcd7482097",
    "authSalt":"d870b1472524fcef2cfd512533b1fb19fe6cf1b555cb5d85d60a636cc5356aba",
    "verifyHash":"5791981c2f0685aa9400597b6bee51d04c59399798e9bcf3cdbeec3d8b50971f",
    "verifierVersion":1,
    "verifierSetAt":1424993616858,
    "locale":"en_US",
    "createdAt":1424993616858,
    "devices":{},
    "lockedAt":null
}
  • 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/[email protected]

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/[email protected]

Request

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

Response

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

{
    "normalizedEmail":"[email protected]",
    "email":"[email protected]",
    "emailCode":"9b4da6ccd05e7c24ce6a6c0d208bc7c9",
    "emailVerified":false,
    "kA":"5e1994b0159081921adb416236058d92bd0715a91c884654e4269c49d467a160",
    "wrapWrapKb":"a746589a4d3db2b0552476bae4fc8c9156d29499eeb0d6583ffd6ddcd7482097",
    "authSalt":"d870b1472524fcef2cfd512533b1fb19fe6cf1b555cb5d85d60a636cc5356aba",
    "verifyHash":"5791981c2f0685aa9400597b6bee51d04c59399798e9bcf3cdbeec3d8b50971f",
    "verifierVersion":1,
    "verifierSetAt":1424993616858,
    "locale":"en_US",
    "createdAt":1424993616858,
    "devices":{},
    "lockedAt":null
}
  • 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

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,
        "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
    }' \
    http://localhost:8000/sessionToken/522c251a1623e1f1db1f4fe68b9594d26772d6e77e04cb68e110c58600f97a77

Request

  • Method : PUT
  • Path : /sessionToken/<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":"......"}

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

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": "468601214f60f4828b6cd5d51d9d99d212e7c73657978955f0f5a5b7e2fa1370",
        "uaBrowser": "Firefox",
        "uaBrowserVersion": "42",
        "uaOS": "Android",
        "uaOSVersion": "5.1",
        "uaDeviceType": "mobile",
        "lastAccessTime": 1437992394186
    }
]
  • 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>..."}

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": "468601214f60f4828b6cd5d51d9d99d212e7c73657978955f0f5a5b7e2fa1370"
    }'

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 : 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": "468601214f60f4828b6cd5d51d9d99d212e7c73657978955f0f5a5b7e2fa1370"
    }'

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 : 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 : DEL /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

{}
  • 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":1425004396952,
    "id":"522c251a1623e1f1db1f4fe68b9594d26772d6e77e04cb68e110c58600f97a77"
}
  • 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 : DEL /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).

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>..."}

createAccountResetToken : PUT /accountResetToken/<tokenId>

Since only one accountResetToken is allowed for each account at any time, any subsequent new token will delete the old one.

Example

curl \
    -v \
    -X PUT \
    -H "Content-Type: application/json" \
    -d '{
        "uid" :  "6044486dd15b42e08b1fb9167415b9ac",
        "data" : "b034061cc2886a3c3c08bd4e9bbc8afc4bc3fc9bca12d5b5d0aa7e0a7f78b9ce",
        "createdAt" : 1425004396952
    }' \
    http://localhost:8000/accountResetToken/da7e3b59fc6021836ed205d2176c11819932c9554bec5a40a1f4178b7f08194d

Request

  • Method : PUT
  • Path : /accountResetToken/<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":"......"}
  • ``

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 : DEL /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
    }' \
    http://localhost:8000/keyFetchToken/4c17443c1bcf5e509bc90904905ea1974900120d3dd34e7061f182cb063f976a

Request

  • Method : PUT
  • Path : /keyFetchToken/<tokenId>
    • tokenId : hex256
  • Params:
    • uid : hex128
    • authKey : hex256
    • keyBundle : hex768
    • 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":"......"}
  • ``

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>..."}

deleteKeyFetchToken : DEL /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":"......"}
  • ``

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 : DEL /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":"[email protected]",
    "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 : DEL /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":"......"}
  • ``

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
  • unlock the account (if already locked)

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":"......"}
  • ``

lockAccount : POST /account/<uid>/lock

This method should:

  • set lockedAt for the account specified
  • store the unlockCode for this account

Example

curl \
    -v \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{
        "unlockCode" : "4aa3ca42fbc2e4d64e634ab92c5a607b",
        "lockedAt" : 1425004396952
    }' \
    http://localhost:8000/account/6044486dd15b42e08b1fb9167415b9ac/lock

Request

  • Method : POST
  • Path : /account/<uid>/lock
    • uid : hex128
  • Params:
    • unlockCode : hex128
    • lockedAt : 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 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":"......"}
  • ``

unlockCode : GET /account/<uid>/unlockCode

Example

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

Request

  • Method : GET
  • Path : /account/uid>
    • uid : hex128
  • Params: none

Response

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

{
    "uid":"6044486dd15b42e08b1fb9167415b9ac",
    "unlockCode":"4aa3ca42fbc2e4d64e634ab92c5a607b"
}
  • 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>..."}

unlockAccount : POST /account/<uid>/unlock

This operation should:

  • unset lockedAt (e.g. null in a database)
  • delete the unlockCode for this account

This operation is idempotent. If you delete an unlockCode twice or an unlockCode that doesn't exist then the operation will still succeed.

Example

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

Request

  • Method : POST
  • Path : /account/<uid>/unlock
    • 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":"......"}
  • ``

(Ends)