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: - Content-Type – application/json
Status Codes: - 200 OK – response contains access token and refresh token
- 400 Bad Request – when required parameters are missing or the request is malformed
- 401 Unauthorized – when authentication fails
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: - Content-Type – application/json
Status Codes: - 200 OK – Success, it responds with the new access token and refresh token
- 400 Bad Request – when required parameters are missing or the request is malformed
- 401 Unauthorized – when refresh token is invalid
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 tokenRequest Headers: - Authorization – the access token as Bearer token
Response Headers: - Content-Type – application/json
Status Codes: - 200 OK – no error, payload contains the updated
expires_in
value - 400 Bad Request – the request is malformed
- 401 Unauthorized – the access token is invalid
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: - Authorization – the access token as Bearer token
Parameters: - refresh_token (string) – the refresh token to revoke
Status Codes: - 204 No Content – the refresh token was deleted
- 400 Bad Request – the request is malformed
- 401 Unauthorized – the access token is invalid or
- 404 Not Found – the refresh token was already revoked or not exists