Login/logout

Teamwire administrators must login first to gain access to the Enterprise API. For security reasons they should also logout after finishing their operations.

---

Login and logout

Login to the Enterprise API

POST /v<api_version>/admin/login/

This endpoint is the first to be called by applications using the Enterprise API in order to be able to call other endpoints. It requires the credentials of an admin account that must have been created, e.g. through registering, and confirmed beforehand.

A successful login establishes a new session which is conveyed through one or more cookies, so the call to this endpoint must keep any cookies returned and supply them in successive calls to other endpoints as shown in the example below.

URL parameters

The following parameters are specified as part of the URL, i.e. /<parameter>/:

Name	Type	Optional	For use by	Description
api_version	String	No	All admins	The Enterprise API version targeted.

POST data

Parameters are supplied as a JSON object with the following elements:

Name	Type	Optional	For use by	Description
email	String	No	All admins	The admin’s email address.
password	String	No	All admins	The admin’s password.
token	String	Depends	All admins	If two factor authentication has been enabled, this parameter is required and must be a valid OTP token for the login to succeed.

Result

The following return values indicate the outcome of the API call:

HTTP status code	Description
200 (OK)	The request was successful, a new Enterprise API session is now active. The received session cookie must be sent along with all successive requests.
401 (Unauthorized)	The request failed because the supplied credentials were invalid, i.e. email address and/or password were not correct. A JSON object as described below is returned that contains additional details.
403 (Forbidden)	The request failed because the admin’s account has been disabled and/or her email address and/or phone number have not been confirmed. A JSON object as described below is returned that details the exact error.
406 (Not acceptable)	The request failed because a two factor authentication (2FA) token is required for a login to this admin account.
409 (Conflict)	The request failed because the admin’s organisation has been disabled.
429 (Too many requests)	The request failed because the API consumer did not wait long enough after the previous failed attempt before trying to login again. A JSON object as described below is returned that contains additional details.

If the request failed with HTTP status codes 401 or 429, a JSON object with the following elements is returned:

Name	Type	Visible to	Description
retry_delay	Integer	All admins	The time in seconds to wait until another login attempt can be performed.

If the request failed with HTTP status code 403, a JSON object with the following elements is returned:

Name	Type	Visible to	Description
confirmed_email	Integer	All admins	1 if the admin’s email address has been confirmed, 0 otherwise.
confirmed_mobile	Integer	All admins	1 if the admin’s mobile phone number has been confirmed, 0 otherwise.
enabled	Integer	All admins	1 if the admin’s account has been confirmed, 0 otherwise.

Example

This code fragment demonstrates how to use the requests module’s session handling to store and transparently supply the needed cookies to a successive request, in this case a call to the groups endpoint. It assumes an API version 12 backend.

import requests

params = {
    "email": "exampleadmin@company.foo",
    "password": "mypassword"
}

try:
    r = session.post(server_url + "/v15/admin/login/", json.dumps(params))
    r.raise_for_status()
except (requests.exceptions.HTTPError, requests.exceptions.ConnectionError) as e:
    print(str(e))
    sys.exit(1)

try:
    r = session.get(args.server_url + "/v15/admin/groups/")
    r.raise_for_status()
except (requests.exceptions.HTTPError, requests.exceptions.ConnectionError) as e:
    print(str(e))
    sys.exit(1)

groups = r.json()

Logout from the Enterprise API

DELETE /v<api_version>/admin/login/

For security and housekeeping reasons applications should always call this endpoint after having finished their Enterprise API operations.

It is safe to call this method even without having logged in beforehand, so it makes perfect sense to call it e.g. from a shutdown handler as shown in the example below.

URL parameters

The following parameters are specified as part of the URL, i.e. /<parameter>/:

Name	Type	Optional	For use by	Description
api_version	String	No	All admins	The Enterprise API version targeted.

Result

The following return values indicate the outcome of the API call:

HTTP status code	Description
200 (OK)	The request was successful, any currently active session will have been terminated.

Example

This code fragment demonstrates how to ensure that the logout endpoint always get called.

import atexit

def logout():
    session.delete(server_url + "/v15/admin/login/")

atexit.register(logout)