Authentication¶
endpoint: /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
Note
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¶
Request type: POST
Parameters
{
"username": "test",
"password": "test",
"grant_type": "password"
}
grant_type
is optional because it is the default used if no one is
passed.
If user is validated the response will contain the JWT, the time to expire (in seconds) and the refresh_token useful to renew the JWT
{
"api": "auth",
"data": {
"access_token": "eyJ0eXAi.....",
"expires_in": 600,
"refresh_token": "51a3f718e7abc712e421f64ea497a323aea4e76f"
},
"method": "post",
"params": [ ],
"url": "https://example.com/api/auth"
}
Once you received the access token you have to use it in every request that require authentication. It can be used in HTTP header
Authorization: Bearer eyJ0eXAi.....
or as query url /api/endpoint?access_token=eyJ0eXAi.....
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
Request type: POST
Parameters
{
"grant_type": "refresh_token",
"refresh_token": "51a3f718e7abc712e421f64ea497a323aea4e76f"
}
If refresh token is valid it returns the new access token
{
"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¶
Calling /auth in GET using the access_token return the updated ‘expires_in’ time.
Request type: GET
It returns
{
"api": "auth",
"data": {
"access_token": "rftJasd3.....",
"expires_in": 48
},
"method": "get",
"params": [ ],
"url": "https://example.com/api/auth"
}
Revoking a refresh token /auth/:refresh_token¶
In order to invalidate an access_token you need to remove it from client and revoke the refresh token
Request type: DELETE
If the refresh token is deleted it responds as HTTP 204 No Content.