API : Authentication Login

Introduction

To access any API function outside of /auth, an access token must be provided. This function is used to authenticate the user against the platform and obtain a token to be used for further requests.

Request

URL	https://api.telecomx.dk/auth/login
Method	POST (preferred) or GET
Query	Only if method is GET
	username	String	Users e-mail address
	password	String	Users password
	smsKey	String	If SMS authentication is required, this should be the SMS code sent to the users phone
	authenticatorToken	String	If authenticator validation is required, this is the time based token generated on the users device.
	cookie	Boolean	True if the server should send a cookie with the token, default false.
	persist	Boolean	True if the token shall not expire until the user explicitly log out. For use in apps.
Body	JSON object (only if method is POST)
	username	String	users e-mail address
	password	String	users password
	smsKey	String	If SMS authentication is required, this should be the SMS code sent to the users phone
	authenticatorToken	String	If authenticator validation is required, this is the time based token generated on the users device.
	cookie	Boolean	True if the server should send a cookie with the token, default false.
	persist	Boolean	True if the token shall not expire until the user explicitly log out. For use in apps.

Body examples

{
  username: 'user@domain.com',
  password: 'mysecret password',
  smsKey: '1563',
  cookie: 0
}

{
  username: 'user@domain.com',
  password: 'mysecret password',
  authenticatorToken: '123456',
  cookie: 0
}

Response

Property	Type	Description
token	String	Token to present on all future requests.
expiresInMinutes	Number	Number of minutes the token will be valid, default 15 and -1 if persist was used.
employee	Id	Id of the employee the token belongs to
customer	Id	Id of the customer the employee belongs to
accessLevel	String	The employees access level (see employee for access levels)
name	String	Name of employee
language	String	The language selected by the employee
customerName	String	Name of the customer the user belongs to
customerFeatures	Array	List of features in the TelecomX platform that the customer has access to. The available features are:
		CUSTOMER - Basics, addresses, financial, usage limits, employees
		SIP - SIP trunks
		MVNO - Mobile phones
		PBX - Hosted PBX
		TCE - Telecom Call Enhancer
		DNS - Domain management
		INTERNET - Fiber & xDSL
		IPTVPRIVATE - TV for private
		IPTVBUSINESS - TV for commercial
		FLEXCARE - Healthcare
		EXTERNAL_LICENCES - Also license management
customerIntegrations	Object	Integrations to third-party systems. Omitted if the user is not a reseller
customerIntegrations.billing	Object	Contains billing integrations
customerIntegrations.billing.economic	Object	Integration for visma e-conomic (only relevant for resellers)
customerIntegrations.billing.economic.enabled	Boolean	True if the integration is enabled, default false.
customerIntegrations.billing.rackbeat	Object	Integration for rackbeat (only relevant for resellers)
customerIntegrations.billing.rackbeat.enabled	Boolean	True if the integration is enabled, default false.
customerIntegrations.licences.also	Object	Integration for Also (only relevant for resellers)
customerIntegrations.licenses.also.enabled	Boolean	True if the integration is enabled, default false.
customerIntegrations.ms365	Object	Integration for Also (only relevant for resellers)
customerIntegrations.ms365.enabled	Boolean	True if the integration is enabled, default false.
customerIntegrations.mvnoPrivate	Object	Integration for Also (only relevant for resellers)
customerIntegrations.mvnoPrivate.enabled	Boolean	True if the integration is enabled, default false.
reseller	String	Id of the reseller the customer (of the user) belongs to.
accountingSystemId	String	Id of customer in 3rd party system.
employeeFeatures	Array	List of features the employee has access to:
		PLAYMAKERSTATUS - access to PlayMaker support site.
		DASHBOARD_EDITOR - permission to edit own PBX dashboards.
		HUMAN_TASK - access to human tasks
		COMMUNICATOR_DEBUG - access to perform debugging in Communicator.
		PORTING - ResellerAdmin has access to Porting
		TELE - ResellerAdmin has access to telecom management
		TV - ResellerAdmin has access to to IPTV management
		FINANCE - ResellerAdmin has access to finance management
		FLEXCARESWAP - permission to perform FlexCare Swap
recordingMode	String	Current call recording mode: ALWAYS - all calls are recorded, DEMAND - only record when requested, NEVER - cannot record. (requires PBX).
skin	String	Name of skin to apply in apps (requires PBX).
impersonatedBy	Id	Id of the user who is currently impersonating the logged in user, if impersonation is in use.
communicatorAccess	Boolean	True if user has access to Communicator. (requires PBX).
recordingAccess	Boolean	True if user has permission to record calls. (requires PBX).
recordingRetension	Number	Number of days recordings are kept (required PBX).

Example

{
  token: '...',
  expiresInMinutes: 15,
  employee: '1234567890ABCDEF12345678',
  language: 'da',
  customer: 'ABCDEF123456789012345678',
  name: 'Donald Duck',
  accessLevel: 'MANAGER',
  customerName: 'Northwind Industries',
  customerFeatures: ['CUSTOMER','SIP','MVNO'],
  customerIntegrations: {
    billing: {
      economic: {
        enabled: true
      },
      rackbeat: {
        enabled: true
      }
    },
    licenses: {
      also: {
        enabled: true
      }
    },
    ms365: {
      enabled: true
    },
    mvnoPrivate: {
      enabled: true
    }
  },
  reseller: '123457890ABCDEF12345678',
  accountingSystemId: '646254r6253563tgbcbn',
  employeeFeatures: [ 'DASHBOARD_EDITOR' ],
  recordingMode: 'NEVER',
  skin: 'EARTH',
  impersonatedBy: '12345678901234567890DEDE',
  communicatorAccess: true,
  recordingAccess: false,
  recordingRetension: 0
}

Errors

Error code	Message	Description
401	credentials_invalid	The supplied username and/or password is invalid
401	account_disabled	The users account has been permanently disabled, login is not possible
401	no_login	Account has access level 'NO_LOGIN'
500	internal_error	Internal server error
401	ipaddress_invalid	The user cannot login from the current location
401	sms_error	SMS authentication is required, but the SMS with the key could not be sent
401	sms_authenticate	Please authenticate using SMS key sent to your mobile phone
401	sms_key_invalid	The SMS key used for authentication is not valid
401	authenticator_authenticate	Please authenticate using one time token generated on your device
401	authenticator_key_invalid	The authenticator key used for authentication is not valid
401	authenticator_setup	Please store the provided key in your authenticator and provide the generated token.
401	m2m_only	M2M authentication is required
400	bad request	Unspecified error

When receiving a 401 authenticator_setup response, the error contains additional fields: key which holds the authenticator key, and totp which holds the otpauth string for presenting as a QR code using the https://api.telecomx.dk/tools/qr API.

How to use a token

The token can be presented in 4 ways:

Method	Description	Example
HTTP header	As an HTTP header adhering to the JWT method (preferred)	Authorization: Bearer <TOKEN-STRING>
Body	As a property in the JSON body on POST requests	{ token: <TOKEN-STRING>, other-arg: 'value' }
Query	As an argument on the URL	?a=b&token=<TOKEN-STRING>
Cookie	In a cookie, set by the server on login (not recommended due to risk of Cross-Site-Scripting exploitation)	n/a

A token will only be valid for the number of minutes specified in expiresInMinutes. Before that period has passed, the client application must call any protected page, to keep the token valid, this will reset the timeout (e.g. if expiresInMinutes = 15, then another 15 minutes is available from the time of the request).

WIKI

Table of Contents