Tokens

Token API

This is the libraries token interface:

use Companion\CompanionApi;

$api = new CompanionApi();
$api->Token()->set($token); // Set a token to use, can override any existing token
$api->Token()->get(); // Returns a SightToken that is currently being used
$api->Token()->save(); // Save the current token
$api->Token()->load(); // Load all saved token
$api->Token()->hasExpired(timestamp); // true||false if a token has expired based on a timestamp

---

Methods of obtaining a SE Header Token

To use the companion library you must first have a SE Header Token, there are two ways to obtain this:

• Manual: Request the Companion App Login and then use your SE credentials to login and activate the token
• Automatic: Provide your SE credentials to the library and it will auto-login.

Note: Automatic login will only work for accounts without a One-Time Password. This can be supported but it is not top-priority right now.

Both paths will require that you manage/store a SightToken object that the library uses. It is worth remembering that while SE do require a token (which is a random hash string), the Companion Library uses a Token Object (SightToken).

The SightToken holds your SE Header Token but it also stores the regional Data-Center url which is required for any request. Once you login to your character, SE will provide the correct companion URL for that Data-Center. This is stored in the token and required for any market requests.

---

Token Management via CompanionConfig

Note: It is highly recommended you manage your own tokens in a private database/storage rather than using the in-built token management.

The library can keep a record of your Sight Access Token information to be able to query against the Sight API. This is optional and by default it will not save any tokens. You can either inform the library to save a token to a file or you can request your token at anytime and save it however you prefer (db, redis, s3, whatever).

The library supports multiple tokens being stored in the same storage unit and will look for one whenever you provide a token name.

If you want the library to record the Sight Access Token information, tell it where to save:

use Companion\Config\CompanionConfig;
CompanionConfig::setTokenFilename('/path/to/save/tokens.json');

Important: The path is not publicly accessible on the internet AND is not within the library itself (composer update will delete it).

---

Using the Companion Token Management

$api = new CompanionApi("name");

If you provide a "name" parameter then the Companion Library will attempt to find a stored token in the file CompanionConfig::setTokenFilename('/path/to/save/tokens.json'). This name is the JSON index, for example, say you have 2 tokens:

{
    "my_token": {  },
    "second_character": {  },
}

If I wanted to use the token for the second character, I could call:

$api = new CompanionApi("second_character");

The library will look in tokens.json and try to find second_character entry and build a token from what is stored there.

---

Using custom token management

Say you have successfully logged in and you now want to store that token. You can get the token object like so:

$token = $api->Token()->get();

This token can then be JSON encoded or serialised and stored (as all object fields are public)

$token = $api->Token()->get();
$token = json_encode($token);

After that, you now have a string, you could save this in your database

$token = $api->Token()->get();
$token = json_encode($token);

$pdo->prepare("INSERT INTO companion_tokens (name, token_json) VALUES ("my_token", ?)")
$pdo->execute([
    $token
]);

Now the token object is in your database.

To reuse this token, fetch it from your database and inject it back into the Companion API during initialise, for example:

$pdo->prepare("SELECT token_json FROM companion_tokens WHERE name = 'my_token' LIMIT 1");
$pdo->execute();

$token = $pdo->fetch();
$token = json_decode($token['token_json']);

// Now build a SightToken object
$token = SightToken::build($token);

// now use it
$api = new CompanionApi($token);