An ebook/comic library service and web client
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

128 lines
3.7 KiB

  1. Authentication API
  2. ==================
  3. .. http:post:: /auth/login
  4. Authenticate with the server and receive a userToken for requests.
  5. **Example request**:
  6. .. sourcecode:: http
  7. POST /auth/login HTTP/1.1
  8. Host: example.tld
  9. Accept: application/json
  10. Authorization: Basic <Base64 Encoded Basic Auth>
  11. **Example response**:
  12. .. sourcecode:: http
  13. HTTP/1.1 200 OK
  14. Vary: Accept
  15. Content-Type: application/json
  16. {
  17. "creationTime": "2018-07-29T11:59:29-05:00",
  18. "enabled": true,
  19. "token": "b94cf5c7-cddc-4610-9d4c-6b8e04088ae8",
  20. "version": 0
  21. }
  22. :<header Accept: Response content type depends on :mailheader:`Accept` header
  23. :<header Authorization: Encoded basic authorization
  24. :>header Content-Type: Depends on :mailheader:`Accept` header of request
  25. :>json datetime creationTime: Creation time for the userToken
  26. :>json datetime expirationTime: Expiration time for the userToken
  27. :>json boolean enabled: Whether the userToken is enabled
  28. :>json string token: UserToken to use for further authentication
  29. :>json int version: Version for the object
  30. :statuscode 200: User successfully logged in
  31. :statuscode 401: Authorization failed
  32. .. http:post:: /auth/bump
  33. Bump user login information.
  34. **Example request**:
  35. .. sourcecode:: http
  36. POST /auth/bump HTTP/1.1
  37. Host: example.tld
  38. Accept: application/json
  39. Authorization: Token <Base64(user:userToken)>
  40. **Example response**:
  41. .. sourcecode:: http
  42. HTTP/1.1 200 OK
  43. Vary: Accept
  44. Content-Type: application/json
  45. {
  46. "lastLoginTime": "2018-07-29T12:15:51-05:00"
  47. }
  48. :<header Accept: Response content type depends on :mailheader:`Accept` header
  49. :<header Authorization: Encoded token authorization
  50. :>header Content-Type: Depends on :mailheader:`Accept` header of request
  51. :>json datetime lastLoginTime: Updated lastLoginTime for the user
  52. :statuscode 200: User last_login_time successfully bumped
  53. :statuscode 401: Authorization failed
  54. .. http:post:: /auth/logout
  55. Logout a user and remove the provided userToken from valid tokens.
  56. **Example request**:
  57. .. sourcecode:: http
  58. POST /auth/logout HTTP/1.1
  59. Host: example.tld
  60. Accept: application/json
  61. Authorization: Token <Base64(user:userToken)>
  62. **Example response**:
  63. .. sourcecode:: http
  64. HTTP/1.1 200 OK
  65. Vary: Accept
  66. Content-Type: application/json
  67. {
  68. "success": true
  69. }
  70. :<header Accept: Response content type depends on :mailheader:`Accept` header
  71. :<header Authorization: Rncoded token authorization
  72. :>header Content-Type: Depends on :mailheader:`Accept` header of request
  73. :>json boolean success: Whether the logout was successful
  74. :statuscode 200: User successfully logged out
  75. :statuscode 401: Authorization failed
  76. Authentication Object Models
  77. ============================
  78. .. json:object:: UserToken
  79. :showexample:
  80. UserToken definition
  81. :property token: The token value, used for authentication
  82. :proptype token: string
  83. :property note: Additional information about the token
  84. :proptype note: string
  85. :property enabled: Determine if a token will be accepted
  86. :proptype enabled: boolean
  87. :property expirationTime: The time that the token becomes invalid, regardless of enabled state
  88. :proptype expirationTime: iso8601
  89. :property creationTime: The time that the token was created
  90. :proptype creationTime: iso8601
  91. :property lastUsageTime: The time that the token was last used
  92. :proptype lastUsageTime: iso8601
  93. :property version: An identifier for the token version
  94. :proptype version: integer