Authentication

Either a token or a session cookie is required for most API resources. API clients usually get a token or a session cookie in exchange for a username, valid password and company identifier.

Obtaining a token

There are two types of token: expiring and permanent.

Expiring (session) tokens

These tokens are granted in exchange for a username, valid password and company identifier, and become invalid after a period of inactivity.

Request details

End point /api-token-auth/
Method POST

Request parameters

username required. Can be a user’s username or email address.
password required for user/password based authentication.
company identifier for the company (usually the subdomain part)
extended_expiration_period (optional) for how many days this token should be valid after creating it, maximum 30 days

Example request

curl -X POST -H 'Content-Type: application/json' \
  -d '{
    "username": "tarsila@viasto.com",
    "password": "top-secret",
    "company": "identifier"
  }' \
  https://acme-inc.interview-suite.com/api/v3/api-token-auth/

Response attributes

When authentication is successful:

curl -X POST -H 'Content-Type: application/json' \
  -d '{
    "username":"tarsila@viasto.com",
    "password":"top-secret",
    "company":"identifier",
    "extended_expiration_period": 10
  }' \
  https://interview-suite.com/api/v3/api-token-auth/

HTTP/1.1 200 OK

{"token": "a9e75326e273e8ef865522ac326b457ef1864e9e"}

When required fields are missing:

curl -X POST -H 'Content-Type: application/json' -d '{}' \
  https://interview-suite.com/api/v3/api-token-auth/

HTTP/1.1 400 BAD REQUEST

{"username": ["This field is required."]}

When content is invalid:

curl -X POST -H 'Content-Type: application/json' \
  -d '{"username":"test' \
  https://interview-suite.com/api/v3/api-token-auth/

HTTP/1.1 400 BAD REQUEST

{"detail": "JSON parse error - Unterminated string starting at: line 1 column 13 (char 12)"}

Token scope

The token belongs to a specific user. When a request is authenticated with this token, the interview suite will authorise it based on the user’s Account Type and in some cases their role in a specific interview process (project).

Token invalidation

These tokens can be invalidated by calling the following URL with the token (see below for mechanisms over which the token can be provided):

https://acme-inc.interview-suite.com/api/v3/api-token-invalidate/

Limitations

Using expiring tokens for browser clients is not recommended; there is no mechanism to include the token on a request made by the browser when loading media resources referred to by a src attribute in the DOM (use session cookies instead).

Named (permanent) tokens

../_images/under-construction.png

This functionality is in active development. Please contact viasto support before using this in production.

An interview suite user who is an Account Owner (priveleged/admin user) can create permanent named tokens within the interview suite on the account settings page. The user usually creates one token per third party service, in order that they can selectively delete access to the service once it’s no longer required.

Tokens are automatically generated by the interview suite, but users can choose to enter a custom value.

Token scope

The token belongs to the company and can be viewed and deleted by all Account Owners in the company. The token has almost all the same privileges that an Account Owner has (other than the ability to create and delete named tokens).

Limitations

Named tokens should be used with care, since they bypass the user-level authorisation enforced by the interview suite. Third party systems who let unprivileged users trigger an API request that authenticates with a named token risk allowing the user to perform higher-privileged actions than they could otherwise perform with a standard interview suite account.

Using a token

API requests should be authorised by including a token in the Authorization header. Both expiring and permanent tokens can be provided in one of two ways:

Token authorization

HTTP header:

Authorization: Token <TOKEN>

Example:

curl \
  -H 'Authorization: Token a9e75326e273e8ef865522ac326b457ef1864e9e' \
  https://acme-inc.interview-suite.com/api/v3/whoami/

HTTP basic auth

../_images/under-construction.png

This functionality is in active development. Please contact viasto support before using this in production.

This is intended for use with a permanent token, the string following the term Basic should be the Base64 encoding of token:<TOKEN> (the ‘username’ is the word token).

Providing a user’s actual password is not supported. It’s necessary to obtain a token first.

HTTP header:

Authorization: Basic <Base64-encoded username:token>

Example:

curl \
  -H 'Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l' \
  https://acme-inc.interview-suite.com/api/v3/whoami/

Authentication on behalf of another user

../_images/under-construction.png

This functionality is partially deprecated. Please contact viasto support before using this in production.

For those users with a special permission “authenticate_on_behalf”, it’s possible to authenticate as another user without their password.

This is specially useful for server side integration, as must happen for ATS Connectors.

Here is the workflow how it must work:

../_images/AuthenticationOnBehalfWorkflowDiagram.png