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.

163 lines
4.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. **Example request with note and expirationTime**
  23. .. sourcecode:: http
  24. POST /auth/login HTTP/1.1
  25. Host: example.tld
  26. Accept: application/json
  27. Authorization: Basic <Base64 Encoded Basic Auth>
  28. Content-Type: application/json
  29. {
  30. "note": "Client API Access",
  31. "expirationTime": "2019-07-29T23:59:59-05:00"
  32. }
  33. **Example response**:
  34. .. sourcecode:: http
  35. HTTP/1.1 200 OK
  36. Vary: Accept
  37. Content-Type: application/json
  38. {
  39. "note": "Client API Access",
  40. "expirationTime": "2019-07-29T23:59:59-05:00",
  41. "creationTime": "2018-07-29T11:59:29-05:00",
  42. "enabled": true,
  43. "token": "b94cf5c7-cddc-4610-9d4c-6b8e04088ae8",
  44. "version": 0
  45. }
  46. :<header Accept: Response content type depends on :mailheader:`Accept` header
  47. :<header Authorization: Encoded basic authorization
  48. :<header Content-Type: Application/json
  49. :<json string note: Note to attach to the created token
  50. :<json iso8601 expirationTime: Expiration time for the userToken
  51. :>header Content-Type: Depends on :mailheader:`Accept` header of request
  52. :>json iso8601 creationTime: Creation time for the userToken
  53. :>json iso8601 expirationTime: Expiration time for the userToken
  54. :>json boolean enabled: Whether the userToken is enabled
  55. :>json string token: UserToken to use for further authentication
  56. :>json int version: Version for the object
  57. :statuscode 200: User successfully logged in
  58. :statuscode 401: Authorization failed
  59. .. http:post:: /auth/bump
  60. Bump user login information.
  61. **Example request**:
  62. .. sourcecode:: http
  63. POST /auth/bump HTTP/1.1
  64. Host: example.tld
  65. Accept: application/json
  66. Authorization: Bearer <Base64(user:userToken)>
  67. **Example response**:
  68. .. sourcecode:: http
  69. HTTP/1.1 200 OK
  70. Vary: Accept
  71. Content-Type: application/json
  72. {
  73. "lastLoginTime": "2018-07-29T12:15:51-05:00"
  74. }
  75. :<header Accept: Response content type depends on :mailheader:`Accept` header
  76. :<header Authorization: Encoded token authorization
  77. :>header Content-Type: Depends on :mailheader:`Accept` header of request
  78. :>json iso8601 lastLoginTime: Updated lastLoginTime for the user
  79. :statuscode 200: User last_login_time successfully bumped
  80. :statuscode 401: Authorization failed
  81. .. http:post:: /auth/logout
  82. Logout a user and remove the provided userToken from valid tokens.
  83. **Example request**:
  84. .. sourcecode:: http
  85. POST /auth/logout HTTP/1.1
  86. Host: example.tld
  87. Accept: application/json
  88. Authorization: Bearer <Base64(user:userToken)>
  89. **Example response**:
  90. .. sourcecode:: http
  91. HTTP/1.1 200 OK
  92. Vary: Accept
  93. Content-Type: application/json
  94. {
  95. "success": true
  96. }
  97. :<header Accept: Response content type depends on :mailheader:`Accept` header
  98. :<header Authorization: Rncoded token authorization
  99. :>header Content-Type: Depends on :mailheader:`Accept` header of request
  100. :>json boolean success: Whether the logout was successful
  101. :statuscode 200: User successfully logged out
  102. :statuscode 401: Authorization failed
  103. Authentication Object Models
  104. ============================
  105. .. json:object:: UserToken
  106. :showexample:
  107. UserToken definition
  108. :property token: The token value, used for authentication
  109. :proptype token: string
  110. :property note: Additional information about the token
  111. :proptype note: string
  112. :property enabled: Determine if a token will be accepted
  113. :proptype enabled: boolean
  114. :property expirationTime: The time that the token becomes invalid, regardless of enabled state
  115. :proptype expirationTime: iso8601
  116. :property creationTime: The time that the token was created
  117. :proptype creationTime: iso8601
  118. :property lastUsageTime: The time that the token was last used
  119. :proptype lastUsageTime: iso8601
  120. :property version: An identifier for the token version
  121. :proptype version: integer