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:
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 or Content-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:
Status Codes:
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.

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:
Status Codes:
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"
}

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:

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:

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
}

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.