Login

Signs a TrakIT user in and returns a token. Send the token in a Token header with every other call of the integration API, for example GetEntity or GetLocations. Sign in once and keep using the token until a call refuses it: see Token expiry. When the integration no longer needs the token, end it with Logout. Only a user with API access can sign in.

How to sign in and read the response: Authentication, Responses.

POST /api/v1/Login
Content-Type: application/json

{
  "User": "jsmith",
  "Password": "your-password"
}

Field	Required	Meaning
`User`	Yes	The user’s TrakIT user ID, or the email address on the user record. Capitals do not matter.
`Password`	Yes	The user’s password. It is case-sensitive.

The request has no Token header: Login is the only call that does not need one.

Rules

Rule	`Info` when it fails
The request has a JSON body.	`LoginInfo must be supplied`
`User` is given.	`User ID or Email must be supplied`
`Password` is given.	`Password must be supplied`
`User` is not only spaces.	`User ID or Email is required`
A `User` with an `@` is a well-formed email address.	`Email ... is invalid`
There have been fewer than five failed sign-ins with this `User` in the last 30 minutes.	`Five unsuccessful attempts made. Try again after 30 minutes.`
The user ID or email address and the password are right.	`User ID / Email or Password is incorrect`
The user record has an email address.	`Sign In Permission Denied`
The user record passes TrakIT’s integrity check. If not, contact TrakIT Support.	`User Hash verification failed`
The user is not locked.	`User account is locked`
Your TrakIT installation has been updated in the last 90 days.	`Sign-in is disabled because this TrakIT installation has not been updated in the last 90 days. ...`
The user may sign in somewhere: at least one access mode is on.	`User account not permitted to logon`
The user has the API access mode.	`User account is not permitted to sign in from the API`
The user’s password has not expired, if your company makes passwords expire. See Password expiry.	`Your password has expired. Sign in to TrakIT in a web browser to change it.`
The user has no two-factor authentication: `Login` cannot take a one-time code.	`Two-factor authentication is on for this user, and the API cannot take a code. Use an API user without two-factor authentication.`
Your company’s sign-in validations, if it has any (User > Login in Validations and actions), pass.	The validation’s own message

A user with two-factor authentication cannot use the integration API, whichever kind of code they use: use a user without it. Login sends such a user no code.

Response

On success, Info holds the token. RetInfo is null, and RowsAffected and Identity are 0.

{
  "Code": 1,
  "Info": "your-token",
  "RetInfo": null,
  "RowsAffected": 0,
  "Scalar": null,
  "Identity": 0
}

Treat the token as an opaque string: send it back exactly as you received it, and keep it as secret as the password.

Notes

Each successful Login starts a new session, listed as an API session on the user’s Session Log tab. Tokens from earlier sign-ins keep working until they end, so sign in again only when a call answers Token invalid or expired.
If the same user is signed in to TrakIT in a web browser from another internet connection, Login signs them out there: the next page they open goes back to the sign-in page. Set aside a user for the integration.
A wrong password, or a user ID or email address that does not exist, counts as a failed sign-in. After five within 30 minutes, TrakIT refuses that User until the oldest of them is more than 30 minutes old, even with the right password. Every three hours, TrakIT emails its system administrators a summary of the failed sign-ins since the last one.
Your company’s sign-in actions, if it has any, run on Login as they do for a sign-in in a web browser.
TrakIT logs every Login call with the User sent, never the password.