Authentication /auth

It used to retrieve an access token to access protected items, renew access token and remove permissions. The access token is a Json Web Token (IETF). More info on authentication

Important

Because of JWT is digital signed using 'Security.salt' you should always remember to change it in app/config/core.php file:

Configure::write('Security.salt', 'my-security-random-string');

It is possible to invalidate all access token released simply changing that value.

Obtain an access token

POST /auth

Authenticate an user to obtain an access token.

Request JSON Object:
 
  • username (string) – the username
  • password (string) – the password
  • grant_type (string) – “password”, the grant type to apply (password is the default, it can be ommitted)
Response Headers:
 
Status Codes:

Example request:

POST /auth HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
Content-Type: application/json

{
    "username": "test",
    "password": "test",
    "grant_type": "password"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "api": "auth",
    "data": {
        "access_token": "eyJ0eXAi.....",
        "expires_in": 600,
        "refresh_token": "51a3f718e7abc712e421f64ea497a323aea4e76f"
        },
    "method": "post",
    "params": [ ],
    "url": "https://example.com/api/auth"
}

Note

Once you received the access token you have to use it in every request that requires authentication. It can be used in HTTP header

Authorization: Bearer <token>

or as query string /api/endpoint?access_token=<token>

Renew the access token

If the access token was expired you need to generate a new one started by refresh token. In this case do not pass the expired access token

POST /auth

Renew an access_token.

Request JSON Object:
 
  • refresh_token (string) – the refresh token to use to renew access token
  • grant_type (string) – “refresh_token”, the grant type to apply
Response Headers:
 
Status Codes:

Example request:

POST /auth HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
Content-Type: application/json

{
    "grant_type": "refresh_token",
    "refresh_token": "51a3f718e7abc712e421f64ea497a323aea4e76f"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "api": "auth",
    "data": {
        "access_token": "rftJasd3.....",
        "expires_in": 600,
        "refresh_token": "51a3f718e7abc712e421f64ea497a323aea4e76f"
        },
    "method": "post",
    "params": [ ],
    "url": "https://example.com/api/auth"
}

Get the updated time to access token expiration

GET /auth

It returns the updated expires_in time for access token

Request Headers:
 
Response Headers:
 
Status Codes:

Example request:

GET /auth HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "api": "auth",
    "data": {
        "access_token": "rftJasd3.....",
        "expires_in": 48
    },
    "method": "get",
    "params": [ ],
    "url": "https://example.com/api/auth"
}

Revoking a refresh token

In order to invalidate an access token you need to remove it from client and revoke the refresh token

DELETE /auth/(string: refresh_token)

Revoke a refresh token

Request Headers:
 
Parameters:
Status Codes: