Authentication

Every call to TrakIT’s API says who is calling. The integration API uses a token that a TrakIT user gets by signing in. The public API uses API keys, each set up for one partner and a few endpoints.

Integration API: login token

1. Sign in with POST /api/v1/Login, with the user ID or email address and the password of a user who has API access.
2. On success, Info holds the token.
3. Send the token in a Token header with every other call:

GET /api/v1/GetJob?Num=EXBL2610045
Token: your-token

Keep the token and use it for every call until it is refused: there is no need to sign in for each call. Every sign-in opens a new session in the user’s sign-in history, and after five failed sign-ins within 30 minutes with the same user ID or email address, TrakIT refuses sign-ins with it for 30 minutes.

These answers mean the token was not accepted:

Info	Means
Token missing in header	The request has no Token header.
Invalid Token, Invalid Token Split	The header holds something that is not a TrakIT token, for example a cut or altered value.
Token invalid or expired	The token has expired, or its session has ended. Sign in again.
User account is locked	The user has been locked since the token was issued.
No such user	The token’s user no longer exists.
API User must be SysAdmin with API Access	The user no longer has API access.
Your password has expired. Sign in to TrakIT in a web browser to change it.	The user’s password has expired.
Database is offline	TrakIT is not available at the moment, for example during maintenance. Try again later.

API access

Only a system administrator with API access can use the integration API. API access is one of the access modes on the User Access page, and only TrakIT Support can turn it on or off. Without it, Login answers User account is not permitted to sign in from the API, and a token issued before it was turned off is refused.

The calls act as that user. The jobs, events, documents and bills an integration creates or changes are recorded under the user’s name, as if the user had done it in TrakIT. Set aside a user for each integration and ask TrakIT Support to give it API access, so that the integration’s changes are easy to tell apart and its access can be withdrawn on its own. A separate user also keeps the integration from disturbing a person: a sign-in through the API counts as the user’s latest sign-in, so if the same user is signed in to TrakIT in a web browser elsewhere, that browser session is signed out.

A user who signs in with two-factor authentication, a code sent by email or an authenticator app, cannot get a token: Login cannot take the code, so it refuses such a user without sending one (Two-factor authentication is on for this user, and the API cannot take a code. Use an API user without two-factor authentication.). Use a user without two-factor authentication for the API.

The usual sign-in rules apply to Login as well: a locked user cannot sign in, repeated wrong passwords pause the user’s sign-ins, and your company’s sign-in validations, if it has any, can refuse it.

Token expiry

A token stays valid as long as it is used: it expires after 7 days without a call. An integration that calls the API at least once a week does not need to sign in again for that reason. A token also ends, before then, when:

• the integration signs it out with Logout;
• the user’s password is changed or reset, wherever that is done: in TrakIT, in the separate TrakIT app or by an administrator;
• the user is locked, or unlocked.

When a call answers Token invalid or expired, sign in again with Login and use the new token.

Each Login gives a new token; tokens from earlier sign-ins keep working until they end. Sign out with Logout a token the integration no longer uses.

Password expiry

If your company makes passwords expire (When your password expires), the API user’s password expires too. From then on, Login and every other call answer Your password has expired. Sign in to TrakIT in a web browser to change it.; only Logout still works. To go on:

1. Sign in to TrakIT in a web browser as the API user, and change the password.
2. Sign the integration in again with Login and the new password: changing the password has ended the user’s other tokens.

Public API: API keys

TrakIT Support sets up the keys of the public API. Each key is allowed only the endpoints it needs, and Support can disable a key at any time. A key that is wrong, disabled or not allowed the endpoint gets Key is disabled, not recognized or permission denied.

Endpoints take the key in different ways:

Endpoints	Send the key
Vendor bills, GetShipment	In an APIKey header: APIKey: your-api-key.
QueryReport, AdvReport	In an APIKey query string parameter.
GetContainerPosition, ExecuteMove	In an Authorization header: Authorization: Bearer your-api-key.
GetList, GetAssetLocation	The entity’s own key, in an APIKey query string parameter.

A vendor bill key is also tied to one supplier, one company and one external user: see How a vendor key works.

To get a key, ask TrakIT Support, saying which endpoints it is for.

Entity API keys

GetList and GetAssetLocation answer for one customer: the entity whose key is sent. That key is not set up by TrakIT Support: it is shown on the entity’s page, as API Key, once Enable API Access is on for the entity. Users who can change the entity see it there and give it to the customer.

The key is valid for the current calendar year. At the start of each year it changes: give the customer the new key from the entity’s page. Turning Enable API Access off for the entity stops its key working at once, on both endpoints.

Keeping credentials safe

• Call the API over HTTPS only.
• Keep passwords, tokens and keys in your system’s secret store, not in code, scripts or documents that others can read, and never send them by email.
• Some endpoints take the key in the query string, so it is part of the address. Keep those addresses out of logs and screenshots you share.
• If a key may have leaked, ask TrakIT Support to disable it and issue a new one. If a token may have leaked, sign it out with Logout. If the API user’s password may have leaked, change it, which also ends all of the user’s tokens, and contact TrakIT Support at once.