Table of Contents
On this page

Token authentication

What is token authentication?

Token authentication means making a request to an API endpoint while also sending a special header that contains an access token. The access token was previously generated by (usually) the same API as the one you are sending requests to and it consists of an alphanumeric string.

How does it work?

In order to protect specific resources, clients need to be authenticated with user/admin roles. These roles are identified from the access token sent via the Authorization header.

When Dotkernel API receives a request, it tries to read the access token.

If it does not find an access token, client has guest role:

  • if the requested endpoint needs no authentication, the requested resource is returned
  • else, a 403 Forbidden response is returned

Else, client's account is identified and client has admin/user role (the one assigned in their account)

  • if the requested endpoint is accessible to the client, the requested resource is returned
  • else, a 403 Forbidden response is returned

Dotkernel API provides out-of-the-box both an admin and a user account.

The admin account with role set to both superuser and admin with the following credentials:

  • identity: admin
  • password: dotkernel

The user account with role set to both user and guest with the following credentials:

  • identify: test@dotkernel.com
  • password: dotkernel

Flow

  • client sends API request with credentials
  • API returns a JSON object containing a new access and refresh token
  • client sends API request using Authentication header containing the previously generated access token
  • API returns requested resource

Note

The first two steps need to executed only once. Access token should be stored and reused for all upcoming requests. Refresh token should be stored and used to refresh expired access token.

For a better overview of the flow, see the below image:

Token authentication flow

Generate admin access token

Send a POST request to the /security/generate-token endpoint with Content-Type header set to application/json.

Set request body to:

{
  "grant_type": "password",
  "client_id": "admin",
  "client_secret": "admin",
  "scope": "api",
  "username": "<identity>",
  "password": "<password>"
}

Note

Replace <identity> with your admin account's identity and <password> with your admin account's password. Both fields come from table admin.

Test using curl

Execute the below command:

curl --location 'https://api.dotkernel.net/security/generate-token' \
--header 'Content-Type: application/json' \
--data-raw '{
  "grant_type": "password",
  "client_id": "admin",
  "client_secret": "admin",
  "scope": "api",
  "username": "admin",
  "password": "dotkernel"
}'

Generate user access token

Send a POST request to the /security/generate-token endpoint with Content-Type header set to application/json.

Set request body to:

{
  "grant_type": "password",
  "client_id": "frontend",
  "client_secret": "frontend",
  "scope": "api",
  "username": "<identity>",
  "password": "<password>"
}

Note

Replace <identity> with your user account's identity and <password> with your user account's password. Both fields come from table user.

Test using curl

Execute the below command:

curl --location 'https://api.dotkernel.net/security/generate-token' \
--header 'Content-Type: application/json' \
--data-raw '{
  "grant_type": "password",
  "client_id": "frontend",
  "client_secret": "frontend",
  "scope": "api",
  "username": "test@dotkernel.com",
  "password": "dotkernel"
}'

Response on success

You should see a 200 OK response with the following JSON body:

{
    "token_type": "Bearer",
    "expires_in": 86400,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.e...wuE39ON1mS5mnTKfA_dSpSWxOmNQdny_AKIbc1qZjMfS24qSUV8HIoOw",
    "refresh_token": "def502005a035c8dfe5456d27e85069813a4f8...0b844e843cd62865662a0e723165752dfd7012491502d3d819c2a61d"
}

Field description:

  • token_type: token type to be set when sending the Authorization header (example: Authorization: Bearer eyJ0e...)
  • expires_in: access token lifetime (modify in: config/autoload/local.php > authentication.access_token_expire)
  • access_token: generated access token (store it for later use)
  • refresh_token: generated refresh token (store it for regenerating expired access token)

Response on failure

You should see a 400 Bad Request response with the following JSON body:

{
    "error": "Invalid credentials.",
    "error_description": "Invalid credentials.",
    "message": "Invalid credentials."
}

Refresh admin access token

Send a POST request to the /security/refresh-token endpoint with Content-Type header set to application/json.

Set request body to:

{
  "grant_type": "refresh_token",
  "client_id": "admin",
  "client_secret": "admin",
  "scope": "api",
  "refresh_token": "<refresh-token>"
}

Test using curl

Execute the below command:

curl --location 'https://api.dotkernel.net/security/refresh-token' \
--header 'Content-Type: application/json' \
--data-raw '{
  "grant_type": "refresh_token",
  "client_id": "admin",
  "client_secret": "admin",
  "scope": "api",
  "refresh_token": "<refresh-token>"
}'

Note

Make sure you replace <refresh-token> with the refresh token generated with the access token.

Refresh user access token

Send a POST request to the /security/refresh-token endpoint with Content-Type header set to application/json.

Set request body to:

{
  "grant_type": "refresh_token",
  "client_id": "frontend",
  "client_secret": "frontend",
  "scope": "api",
  "refresh_token": "<refresh-token>"
}

Test using curl

Execute the below command:

curl --location 'https://api.dotkernel.net/security/refresh-token' \
--header 'Content-Type: application/json' \
--data-raw '{
  "grant_type": "refresh_token",
  "client_id": "frontend",
  "client_secret": "frontend",
  "scope": "api",
  "refresh_token": "<refresh-token>"
}'

Note

Make sure you replace <refresh-token> with the refresh token generated with the access token.

Response on success

You should see a 200 OK response with the following JSON body:

{
    "token_type": "Bearer",
    "expires_in": 86400,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.e...wuE39ON1mS5mnTKfA_dSpSWxOmNQdny_AKIbc1qZjMfS24qSUV8HIoOw",
    "refresh_token": "def502005a035c8dfe5456d27e85069813a4f8...0b844e843cd62865662a0e723165752dfd7012491502d3d819c2a61d"
}

Field description:

  • token_type: token type to be set when sending the Authorization header (example: Authorization: Bearer eyJ0e...)
  • expires_in: access token lifetime (change here: config/autoload/local.php authentication->access_token_expire)
  • access_token: generated access token (store it for later use)
  • refresh_token: generated refresh token (store it for regenerating expired access token)

Response on failure

You should see a 401 Unauthorized response with the following JSON body:

{
    "error": "invalid_request",
    "error_description": "The refresh token is invalid.",
    "hint": "Cannot decrypt the refresh token",
    "message": "The refresh token is invalid."
}

Test admin authentication flow

Step 1: Fail to fetch protected API content

Try to view your admin account by executing:

curl --location 'https://api.dotkernel.net/admin/my-account'

You should get a 403 Forbidden JSON response.

Step 2: Generate access token

Generate admin access token by executing:

curl --location 'https://api.dotkernel.net/security/generate-token' \
--header 'Content-Type: application/json' \
--data-raw '{
  "grant_type": "password",
  "client_id": "admin",
  "client_secret": "admin",
  "scope": "api",
  "username": "admin",
  "password": "dotkernel"
}'

You should get a 200 OK JSON response.

Store the value of access_token for later use.

Step 3: Successfully fetch protected API content

Try again viewing your admin account by executing:

curl --location 'https://api.dotkernel.net/admin/my-account' \
--header 'Authorization: Bearer <access_token>'

Replace <access_token> with the previously stored access token.

You should get a 200 OK JSON response with the requested resource in the body.

Test user authentication flow

Step 1: Fail to fetch protected API content

Try to view your admin account by executing:

curl --location 'https://api.dotkernel.net/user/my-account'

You should get a 403 Forbidden JSON response.

Step 2: Generate access token

Generate admin access token by executing:

curl --location 'https://api.dotkernel.net/security/generate-token' \
--header 'Content-Type: application/json' \
--data-raw '{
  "grant_type": "password",
  "client_id": "frontend",
  "client_secret": "frontend",
  "scope": "api",
  "username": "test@dotkernel.com",
  "password": "dotkernel"
}'

You should get a 200 OK JSON response.

Store the value of access_token for later use.

Step 3: Successfully fetch protected API content

Try again viewing your admin account by executing:

curl --location 'https://api.dotkernel.net/user/my-account' \
--header 'Authorization: Bearer <access_token>'

Replace <access_token> with the previously stored access token.

You should get a 200 OK JSON response with the requested resource in the body.