Authentication /auth
¶
/auth
endpoint is responsible for login related actions.
With it a user is able to login and to get user login data.
Different actions are supported:
- standard login - providing username and password and without
Authorization
header - token renew - with
Authorization
header and without username and password - whoami - get logged user profile data
- profile update - logged user profile data
- credential change request - request to update password
- credential change update - actual password update action using secret hash
Login¶
-
POST
/auth
¶ Perform login.
Form Parameters: - username – Username of user to be logged in. To be omitted when renewing token.
- password – Password of user to be logged in. To be omitted when renewing token.
Request Headers: - Authorization – (Optional) Use only in token renew, prefixed with
Bearer
.
Status Codes: - 200 OK – Login successful.
- 401 Unauthorized – Unauthorized user, or invalid renew token.
Response JSON Object: - meta.jwt – The JSON Web Token to be used to authenticate (in header Authorization).
- meta.renew – The renew token, to be used to reiterate login process when JWT expires.
Example request (login with username and password): since this is not a JSON API request you MUST use
Content-Type: application/json
orContent-Type: application/x-www-form-urlencoded
, see example below.POST /auth HTTP/1.1 Host: example.com Accept: application/vnd.api+json Content-Type: application/json { "username" : "bedita", "password" : "bedita" }
Same request using classic
Content-Type: application/x-www-form-urlencoded
POST /auth HTTP/1.1 Host: example.com Accept: application/vnd.api+json Content-Type: application/x-www-form-urlencoded username=bedita&password=bedita
Example response:
HTTP/1.1 200 OK Content-Type: application/vnd.api+json { "links": { "self": "http://example.com/auth", "home": "http://example.com/home" }, "meta": { "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJiZWRpdGEiLCJibG9ja2VkIjpmYWxzZSwibGFzdF9sb2dpbiI6IjIwMTYtMDgtMDFUMTM6MTk6MzkrMDAwMCIsImxhc3RfbG9naW5fZXJyIjpudWxsLCJudW1fbG9naW5fZXJyIjowLCJjcmVhdGVkIjoiMjAxNi0wOC0wMVQxMzoxOToyOSswMDAwIiwibW9kaWZpZWQiOiIyMDE2LTA4LTAxVDEzOjE5OjI5KzAwMDAiLCJyb2xlcyI6W10sImlzcyI6Imh0dHA6XC9cLzEwLjAuODMuNDo4MDgwIiwiaWF0IjoxNDcwMDU4NTE3LCJuYmYiOjE0NzAwNTg1MTcsImV4cCI6MTQ3MDA2NTcxN30.rGcCEKiYjETnkaKVgG5-gJxIMXALVaZ4MeV5aKbWtQE", "renew": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC8xMC4wLjgzLjQ6ODA4MCIsImlhdCI6MTQ3MDA1ODUxNywibmJmIjoxNDcwMDU4NTE3LCJzdWIiOjEsImF1ZCI6Imh0dHA6XC9cLzEwLjAuODMuNDo4MDgwXC9hdXRoIn0.mU3QToPvc0uY-XQRhDA1F2hfpRjjT2ljSerKQygk2T8" } }
Example request (token renewal):
POST /auth HTTP/1.1 Host: example.com Accept: application/vnd.api+json Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC8xMC4wLjgzLjQ6ODA4MCIsImlhdCI6MTQ3MDA1ODUxNywibmJmIjoxNDcwMDU4NTE3LCJzdWIiOjEsImF1ZCI6Imh0dHA6XC9cLzEwLjAuODMuNDo4MDgwXC9hdXRoIn0.mU3QToPvc0uY-XQRhDA1F2hfpRjjT2ljSerKQygk2T8
Example response: (same as above, with new JWT and renew token)
Who Am I?¶
-
GET
/auth/user
¶ Get logged user profile data.
Request Headers: - Authorization – Use token prefixed with
Bearer
.
Status Codes: - 200 OK – Get operation successful.
- 401 Unauthorized – Unauthorized user, user not logged.
Response JSON Object: - data – User profile data
Example request
{token} is JWT token from previuos login and renew examples:
GET /auth/user HTTP/1.1 Host: example.com Accept: application/vnd.api+json Authorization: Bearer {token}
Example response:
HTTP/1.1 200 OK Content-Type: application/vnd.api+json { "data": { "id": "2", "type": "users", "attributes": { "username": "gustavo", "blocked": false, "last_login": "2016-10-06T08:17:36+00:00", "last_login_err": null, "num_login_err": 0, "name": "Gustavo", "surname": "Supporto" } }, "links": { "self": "http://example.com/auth/user", "home": "http://example.com/home" }, }
Note: some fields in “attributes” are missing for brevity.
- Authorization – Use token prefixed with
Update user profle¶
-
PATCH
/auth/user
¶ Update logged user profile data with some restrictions. For basic security reasons some fields are not directly changeable: username, email and password. Only exception: password may be changed if current valid password is provided in old_password field.
Request Headers: - Authorization – Use token prefixed with
Bearer
.
Status Codes: - 200 OK – Get operation successful.
- 401 Unauthorized – Unauthorized user, user not logged.
Response JSON Object: - data – User profile data
Example request
{token} is JWT token from previuos login and renew examples:
PATCH /auth/user HTTP/1.1 Host: example.com Authorization: Bearer {token} Accept: application/vnd.api+json Content-Type: application/json { "city" : "Bologna", "country" : "Italy" }
Example response:
HTTP/1.1 200 OK Content-Type: application/vnd.api+json { "data": { "id": "2", "type": "users", "attributes": { "username": "gustavo", "name": "GUstavo", "surname": "Supporto" "city" : "Bologna", "country" : "Italy" } }, "links": { "self": "http://example.com/auth/user", "home": "http://example.com/home" }, }
Note: some fields in “attributes” are missing for brevity.
Example of a password change request
PATCH /auth/user HTTP/1.1 Host: example.com Authorization: Bearer {token} Accept: application/vnd.api+json Content-Type: application/json { "password" : "a new super strong password", "old_password" : "my current password" }
- Authorization – Use token prefixed with
Credentials change¶
Authentications credential change works in two steps:
- a credential change request action
- an actual credential change using a secret hash
Only use case currently supported is password
change.
After a request action an email is sent to requesting user containing a URL with a secret hash to actually perform the change.
-
POST
/auth/change
¶ Request a credential change.
Form Parameters: - contact – Email of user requesting credendials change.
- change_url – Change URL that will be sent via email.
Status Codes: - 204 No Content – No content on operation success.
- 400 Bad Request – On malformed or missing input data.
- 404 Not Found – If no user is found.
Example request: Since this is not a JSON API request you MUST use
Content-Type: application/json
POST /auth/change HTTP/1.1 Content-Type: application/json { "contact": "{my email}", "change_url": "{change url}" }
A change_url
is required in order to create the URL that will be sent to the user in the form
{change_url}?uuid={uuid}
where {uuid}
is a system generated hash that will expire after 24h.
In your change_url
page you will have to read the uuid
query parameter and proceed to actual change performing the following request.
-
PATCH
/auth/change
¶ Perform a credential (password) change.
Form Parameters: - uuid – Secret UUID sent via email in
change_url
. - password – New user password.
- login – Optional boolean parameter, if
true
a login is also performed.
Status Codes: - 200 OK – On operation success.
- 400 Bad Request – On malformed or missing input data.
- 404 Not Found – Not found if provided UUID is incorrect or expired.
Example request: Since this is not a JSON API request you MUST use
Content-Type: application/json
PATCH /auth/change HTTP/1.1 Content-Type: application/json { "uuid": "{uuid}", "password": "{new password}", "login": true }
- uuid – Secret UUID sent via email in
Response will contain user data as in previous Who Am I? request.
If "login"
is true a login is also performed and JWT access token and refresh token tokens are returned in "meta"
section for immediate use. This key is optional, if missing "login": false
is assumed.