Fetching User Data From Tokens (JavaScript friendly version)

The Trongate framework comes with two API endpoints for fetching user data from tokens.  They are:

• Your base URL followed by trongate_tokens/id
• Your base URL followed by trongate_tokens/user

Both of these API endpoints accept HTTP GET requests and can be tested via the Trongate Api Manager.

Adding Your Token To The Header

To use Trongate's token management system in a stateless environment, you'll have to attach a valid token onto the header of your HTTP requests.

In vanilla JavaScript this can be achieved with the following code:

setRequestHeader("trongateToken",token)

The 'Fetch Trongate User ID' Endpoint​

The 'Fetch Trongate User ID' endpoint, evaluates a token and attempts to return a Trongate User ID for the user whom the token has been assigned to.  The URL for this endpoint is your base URL followed by trongate_tokens/id

If the token is valid and a Trongate User ID is found, then a 200 HTTP response code will be produced and the HTTP response body with be a numeric value that matches the Trongate User ID for the end user.

The screenshot below shows a successful user ID request being made, using the Trongate API Manager:

Fetching a Trongate User ID

If a valid token is not presented to the server then the server will issue a 401 HTTP response code and the word 'false' will be outputted.  For example:

an unsuccessful attempt to fetch a Trongate User ID

function id() {

    die(); //disable this endpoint!

    //get the trongate_user_id

    if (!isset($_SERVER['HTTP_TRONGATETOKEN'])) {
        http_response_code(422);
        echo 'no token'; die();
    } else {
        $token = $_SERVER['HTTP_TRONGATETOKEN'];
        $result = $this->model->get_one_where('token', $token, 'trongate_tokens');

        if ($result == false) {
            http_response_code(401);
            echo 'false';
            die();
        } else {
            http_response_code(200);
            echo $result->user_id;
            die();
        }
    }
}

The 'Fetch Trongate User Obj' Endpoint

The 'Fetch Trongate User Obj' endpoint, evaluates a token and attempts to return a Trongate User Object for the user whom the token has been assigned to.  The URL for this endpoint is your base URL followed by trongate_tokens/user​

If the token is valid and successfully matched to a user, then a 200 HTTP response code will be produced and the HTTP response body will contain a JSON string containing information relating to the user.

The screenshot below shows a successful request being made, using the Trongate API Manager:

successfully fetching a user object with Trongate's API Manager

Below shows an example of the kind of data that we can expect to receive from the 'Fetch Trongate User Obj' endpoint:

{
   "trongate_user_code":"dytcGEc47h6VCmYmrJLwH5CPx8GMWcKa",
   "user_level_id":"1",
   "user_level":"admin",
   "token":"r8Ex_25FoYFSsrJTn3wezn6wzW8XRLkf",
   "trongate_user_id":"1",
   "expiry_date":"1629508409"
}

Understanding The User Object

The user object that gets returned after a successful request, contains the following properties:

• trongate_user_code - the value for this property corresponds with the 'code' column on the 'trongate_users' table.
  
• user_level_id - this property contains a value that matches the 'id' column, for the user, from the 'trongate_user_levels' table.
  
• user_level - this property contains the value, for the user, that's stored on the 'level_title' column of the 'trongate_user_levels' table.
• token - the 'token' property contains the user's validated token.  This corresponds with the value, for the user, that's stored on the 'token' column on the 'trongate_tokens' table.
• trongate_user_id - this property contains the user's 'Trongate User ID'.  This is a numeric value, for the user, that corresponds with the 'id' column of the 'trongate_users' table.
• expiry_date - finally, we have an expiry_date property.  This contains a Unix timestamp that represents the date and time when the token will expire.

The screenshot below shows an example of the kind of response that we can expect to receive when a user object request is unsuccessful:

an unsuccessful user object request

    function user() {

    die(); //disable this endpoint!

    //get the trongate user object
    if (!isset($_SERVER['HTTP_TRONGATETOKEN'])) {
        http_response_code(422);
        echo 'No token!';
        die();
    } else {
        $params['token'] = $_SERVER['HTTP_TRONGATETOKEN'];
        $sql = 'SELECT
                    trongate_users.code as trongate_user_code,
                    trongate_users.user_level_id,
                    trongate_user_levels.level_title as user_level,
                    trongate_tokens.token,
                    trongate_tokens.user_id as trongate_user_id,
                    trongate_tokens.expiry_date
                FROM
                    trongate_tokens
                INNER JOIN
                    trongate_users
                ON
                    trongate_tokens.user_id = trongate_users.id
                INNER JOIN
                    trongate_user_levels
                ON
                    trongate_users.user_level_id = trongate_user_levels.id
                WHERE
                    trongate_tokens.token = :token';

        $rows = $this->model->query_bind($sql, $params, 'object');

        if (isset($rows[0])) {
            http_response_code(200);
            echo json_encode($rows[0]);
            die();
        } else {
            http_response_code(400);
            echo 'Unable to match token with user.';
            die();
        }
    }
}