An API access is an open route into your teamspace data – powerful and correspondingly sensitive. This article brings together the security principles that appear scattered across the individual guides into one overview. Anyone who grants or manages API access should know them.
Basic rule: the API has the same rights as the web interface
An API user has exactly the permissions they also have in the web app – no more and no less.
- Anyone who may delete projects in the interface can do so via the API too. There is no way to prevent that – and you also cannot stop a person from writing their own app for it.
- Anyone who may not book times in the interface cannot do so via the API either.
The only exception is access via an API access authorisation (interface authentication): there, no user rights apply, only the rights you give the access authorisation itself. This is exactly why it is the safer route for devices and services – see API access authorisation for terminals & services.
Consequence: Control a person’s API access via their normal permissions in teamspace. The API is neither an extra loophole nor an extra barrier.
Choosing the right type of access
teamspace knows two ways to authorise against the API – with different security profiles:
- Device password (personal access): tied to a specific person; the application acts with their rights. Right for scripts and integrations on behalf of a person. Guide: Create and use a device password (API token).
- API access authorisation (neutral access): tied to no specific user; the rights are tuned finely. Right for devices and services such as a time-clocking terminal. Guide: API access authorisation for terminals & services.
Rule of thumb: Devices and unattended services get a neutral access authorisation – not the personal password of an employee.
The principle of minimal rights
Always grant only as many permissions as the specific use case needs.
- For the API access authorisation, this means: activate only the options actually used. A terminal that should only check in and out needs no “Detailed” right (access to absence details such as sickness or leave).
- Restrict the “Employee” field to the people the access may genuinely concern.
- For device passwords: a separate password per application, so individual accesses can be blocked on purpose.
IP address protection
For stationary applications – for example a time-clocking terminal at a fixed location – IP address protection makes sense. The access then works only from the permitted network; even intercepted credentials are worthless from outside.
Revoking and renewing access
- A device password can be revoked individually at any time without changing your main password – a clear advantage over logging in with your personal password.
- The password is shown only once when created. Via “Change password” you regenerate it; the old one then becomes invalid. Use this as soon as you suspect that credentials have been compromised.
Two-factor authentication
If 2FA is enabled for an account, a token can no longer be created directly via the API (POST api/device). The device password is then created via the web interface. 2FA increases the security of the account and should be active for accounts with API access.
The “Synchronisation” prerequisite
Creating device passwords requires the “Synchronisation” permission. Grant it deliberately only to accounts that genuinely need API access – it is effectively the entry ticket to the API.
Related topics
- Create and use a device password (API token) API How-to
- API access authorisation for terminals & services API Configuration
- Topic: Permissions Permissions