Skip to content

Latest commit

 

History

History
2628 lines (2007 loc) · 61.4 KB

API.md

File metadata and controls

2628 lines (2007 loc) · 61.4 KB

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

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
  • Subscriptions:
    • createAccountSubscription : PUT /account/:id/subscriptions/:subscriptionId
    • fetchAccountSubscriptions : GET /account/:id/subscriptions
    • getAccountSubscription : GET /account/:id/subscriptions/:subscriptionId
    • deleteAccountSubscription : DELETE /account/:id/subscriptions/:subscriptionId
    • cancelAccountSubscription : POST /account/:id/subscriptions/:subscriptionId/cancel
    • reactivateAccountSubscription : POST /account/:id/subscriptions/:subscriptionId/reactivate

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

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

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

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 : 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
  • Params:
    • verified : boolean
    • enable : boolean

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
  • Params:
    • count : int

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

createAccountSubscription : PUT /account/:id/subscriptions/:subscriptionId

Example


curl \
 -v \
 -X PUT \
 -H "Content-Type: application/json" \
 -d '{
"productId" : "exampleProduct1",
"createdAt" : 1424832691282
}' \
 http://localhost:8000/account/6044486dd15b42e08b1fb9167415b9ac/subscriptions/sub8675309

Request

  • Method : PUT
  • Path : /account/<uid>/subscriptions/<subscriptionId>
    • uid : hex
    • subscriptionId : string255
  • Params:
    • productId: Name of the subscribed product from the upstream payment system
    • createdAt: Date of subscription creation

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

fetchAccountSubscriptions : GET /account/:id/subscriptions

Example


curl \
 -v \
 -X GET \
 -H "Content-Type: application/json" \
 http://localhost:8000/account/6044486dd15b42e08b1fb9167415b9ac/subscriptions

Request

  • Method : GET
  • Path : /account/<uid>/subscriptions
    • uid : hex

Response


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

[
{
"uid": 6044486dd15b42e08b1fb9167415b9ac,
"subscriptionId": "sub8675309",
"productId": "exampleProduct1",
"createdAt": 1424832691282
},
{
"uid": 6044486dd15b42e08b1fb9167415b9ac,
"subscriptionId": "sub999",
"productId": "exampleProduct2",
"createdAt": 1424832691282
},
{
"uid": 6044486dd15b42e08b1fb9167415b9ac,
"subscriptionId": "sub987",
"productId": "exampleProduct3",
"createdAt": 1424832691282
}
]
  • Status Code : 200 OK
    • Content-Type : application/json
    • Body : [{}]
      • subscriptionId: ID for the subscription from the upstream payment system
      • productId: Name of the subscribed product from the upstream payment system
      • createdAt: Date of subscription creation
  • Status Code : 500 Internal Server Error
    • Conditions: if something goes wrong on the server
    • Content-Type : application/json
    • Body : {"code":"InternalError","message":"..."}

getAccountSubscription : GET /account/:id/subscriptions/:subscriptionId

Example


curl \
 -v \
 -X GET \
 -H "Content-Type: application/json" \
 http://localhost:8000/account/6044486dd15b42e08b1fb9167415b9ac/subscriptions/sub8675309

Request

  • Method : GET
  • Path : /account/<uid>/subscriptions/<subscriptionId>
    • uid : hex
    • subscriptionId : string255

Response


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

{
"uid": 6044486dd15b42e08b1fb9167415b9ac,
"subscriptionId": "sub8675309",
"productId": "exampleProduct1",
"createdAt": 1424832691282
}
  • Status Code : 200 OK
    • Content-Type : application/json
    • Body : {}
      • subscriptionId: ID for the subscription from the upstream payment system
      • productId: Name of the subscribed product from the upstream payment system
      • createdAt: Date of subscription creation
  • Status Code : 500 Internal Server Error
    • Conditions: if something goes wrong on the server
    • Content-Type : application/json
    • Body : {"code":"InternalError","message":"..."}

deleteAccountSubscription : DELETE /account/:id/subscriptions/:subscriptionId

Example


curl \
 -v \
 -X DELETE \
 -H "Content-Type: application/json" \
 http://localhost:8000/account/6044486dd15b42e08b1fb9167415b9ac/subscriptions/sub8675309

Request

  • Method : DELETE
  • Path : /account/<uid>/subscriptions/<subscriptionId>
    • 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":"..."}

cancelAccountSubscription : POST /account/:id/subscriptions/:subscriptionId/cancel

Example


curl \
 -v \
 -X DELETE \
 -H "Content-Type: application/json" \
 -d '{"cancelledAt":1557844225547}' \
 http://localhost:8000/account/6044486dd15b42e08b1fb9167415b9ac/subscriptions/sub8675309/cancel

Request

  • Method : POST
  • Path : /account/<uid>/subscriptions/<subscriptionId>/cancel
    • uid : hex
    • subscriptionId : string255
  • Params:
    • cancelledAt: uint64

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 subscription(uid,subscriptionId) 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":"..."}

reactivateAccountSubscription : POST /account/:id/subscriptions/:subscriptionId/reactivate

Example


curl \
 -v \
 -X DELETE \
 -H "Content-Type: application/json" \
 http://localhost:8000/account/6044486dd15b42e08b1fb9167415b9ac/subscriptions/sub8675309/reactivate

Request

  • Method : POST
  • Path : /account/<uid>/subscriptions/<subscriptionId>/reactivate
    • uid : hex
    • subscriptionId : string255

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 subscription(uid,subscriptionId) is not found in the database or is not in the cancelled state
    • 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":"..."}