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
163 lines
4.7 KiB
Authentication API
|
|
==================
|
|
|
|
.. http:post:: /auth/login
|
|
|
|
Authenticate with the server and receive a userToken for requests.
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
POST /auth/login HTTP/1.1
|
|
Host: example.tld
|
|
Accept: application/json
|
|
Authorization: Basic <Base64 Encoded Basic Auth>
|
|
|
|
**Example response**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 200 OK
|
|
Vary: Accept
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"creationTime": "2018-07-29T11:59:29-05:00",
|
|
"enabled": true,
|
|
"token": "b94cf5c7-cddc-4610-9d4c-6b8e04088ae8",
|
|
"version": 0
|
|
}
|
|
|
|
**Example request with note and expirationTime**
|
|
|
|
.. sourcecode:: http
|
|
|
|
POST /auth/login HTTP/1.1
|
|
Host: example.tld
|
|
Accept: application/json
|
|
Authorization: Basic <Base64 Encoded Basic Auth>
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"note": "Client API Access",
|
|
"expirationTime": "2019-07-29T23:59:59-05:00"
|
|
}
|
|
|
|
**Example response**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 200 OK
|
|
Vary: Accept
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"note": "Client API Access",
|
|
"expirationTime": "2019-07-29T23:59:59-05:00",
|
|
"creationTime": "2018-07-29T11:59:29-05:00",
|
|
"enabled": true,
|
|
"token": "b94cf5c7-cddc-4610-9d4c-6b8e04088ae8",
|
|
"version": 0
|
|
}
|
|
|
|
:<header Accept: Response content type depends on :mailheader:`Accept` header
|
|
:<header Authorization: Encoded basic authorization
|
|
:<header Content-Type: Application/json
|
|
:<json string note: Note to attach to the created token
|
|
:<json iso8601 expirationTime: Expiration time for the userToken
|
|
:>header Content-Type: Depends on :mailheader:`Accept` header of request
|
|
:>json iso8601 creationTime: Creation time for the userToken
|
|
:>json iso8601 expirationTime: Expiration time for the userToken
|
|
:>json boolean enabled: Whether the userToken is enabled
|
|
:>json string token: UserToken to use for further authentication
|
|
:>json int version: Version for the object
|
|
:statuscode 200: User successfully logged in
|
|
:statuscode 401: Authorization failed
|
|
|
|
.. http:post:: /auth/bump
|
|
|
|
Bump user login information.
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
POST /auth/bump HTTP/1.1
|
|
Host: example.tld
|
|
Accept: application/json
|
|
Authorization: Bearer <Base64(user:userToken)>
|
|
|
|
**Example response**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 200 OK
|
|
Vary: Accept
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"lastLoginTime": "2018-07-29T12:15:51-05:00"
|
|
}
|
|
|
|
:<header Accept: Response content type depends on :mailheader:`Accept` header
|
|
:<header Authorization: Encoded token authorization
|
|
:>header Content-Type: Depends on :mailheader:`Accept` header of request
|
|
:>json iso8601 lastLoginTime: Updated lastLoginTime for the user
|
|
:statuscode 200: User last_login_time successfully bumped
|
|
:statuscode 401: Authorization failed
|
|
|
|
.. http:post:: /auth/logout
|
|
|
|
Logout a user and remove the provided userToken from valid tokens.
|
|
|
|
**Example request**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
POST /auth/logout HTTP/1.1
|
|
Host: example.tld
|
|
Accept: application/json
|
|
Authorization: Bearer <Base64(user:userToken)>
|
|
|
|
**Example response**:
|
|
|
|
.. sourcecode:: http
|
|
|
|
HTTP/1.1 200 OK
|
|
Vary: Accept
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"success": true
|
|
}
|
|
|
|
:<header Accept: Response content type depends on :mailheader:`Accept` header
|
|
:<header Authorization: Rncoded token authorization
|
|
:>header Content-Type: Depends on :mailheader:`Accept` header of request
|
|
:>json boolean success: Whether the logout was successful
|
|
:statuscode 200: User successfully logged out
|
|
:statuscode 401: Authorization failed
|
|
|
|
Authentication Object Models
|
|
============================
|
|
|
|
.. json:object:: UserToken
|
|
:showexample:
|
|
|
|
UserToken definition
|
|
|
|
:property token: The token value, used for authentication
|
|
:proptype token: string
|
|
:property note: Additional information about the token
|
|
:proptype note: string
|
|
:property enabled: Determine if a token will be accepted
|
|
:proptype enabled: boolean
|
|
:property expirationTime: The time that the token becomes invalid, regardless of enabled state
|
|
:proptype expirationTime: iso8601
|
|
:property creationTime: The time that the token was created
|
|
:proptype creationTime: iso8601
|
|
:property lastUsageTime: The time that the token was last used
|
|
:proptype lastUsageTime: iso8601
|
|
:property version: An identifier for the token version
|
|
:proptype version: integer
|