Authenticate

Given valid Vendor credentials, this route returns an access token authenticating you for data retrieval. Tokens are good for three days from generation. Note that all credentials for an organization are not created equal as what data you can retrieve is tied to the credentials permissions within that organization.

You may authenticate with either a username and password or a refresh_token. Provide one or the other, not both.

Verb	POST
Endpoint	{base-url}/authenticate/
Max Page Size	N/A

Request Body

Authenticate with a username and password:

{
  "username": "me@domain.tld",
  "password": "s3cur3P@ssw0rd"
}

Refresh Token

Alternatively, supply a refresh_token in place of the username and password. A refresh token is a long-lived credential you obtain once through the Vendor Client site and then reuse on this route. It is the required option for accounts whose sign-in is federated to a third-party identity provider, as those accounts have no password to send here.

{
  "refresh_token": "<your refresh token>"
}

Returns

On Success

An object containing your access token.

Response Body

Response Body

{
  "accessToken": "9f57c00f-a92d-49e5-86fd-0052b56e0161",
  "userName": "me@domain.tld",
  "issued": "9/3/2020 11:17:40 PM",
  "expires": "9/6/2020 11:17:40 PM"
}

AuthenticationInformation Definition

Attribute	Type	Description
accessToken	string	The bearer token to use in subsequent API requests.
userName	string	The username associated with the token.
issued	string	The date and time the token was issued. Non-ISO, culture-formatted datetime string (e.g. 9/3/2020 11:17:40 PM).
expires	string	The date and time the token expires. Non-ISO, culture-formatted datetime string (e.g. 9/6/2020 11:17:40 PM).

On Error

HTTP Code	Error Code	Definition
422	VALIDATION_ERROR	The body was not a JSON object, or neither, or both, credential options were provided. Supply exactly one: a username and password, or a refresh_token.
403	INVALID_LOGIN	Your username or password was incorrect, or your refresh token is no longer valid.
408	REQUEST_TIMEOUT	The login took longer than the per-request time budget (see Concepts). No token was issued. Retry.
500	VN_INTERNAL_ERROR	The login could not be completed for a reason on our side. Your credentials were not necessarily wrong, so treat this as a retryable outage rather than a rejected login.