Permissions and data scope

Overview

Every REST API request runs as the token's user. See Authentication for how the token decides that user.

TimeLog then checks that user's privileges per operation. Two things follow from this:

• Whether the call is allowed. Some operations need a privilege, for example a project privilege that covers the project you address. Without it, the call fails.
• Which rows you get back. Some operations return only the data the user's privileges cover, for example only the projects the user may see. A shorter list is not an error.

Requirements are documented per operation, and they can differ between operations on the same object. For example, deleting another employee's expense accepts fewer privileges than reading it.

How a privilege failure looks

A missing privilege does not always come back the same way. Depending on the operation, you get one of these:

Business-rule codes that mean "the user lacks a privilege" include:

So check Code and Details[].ErrorCode, not only the HTTP status. A privilege failure is not fixed by retrying with the same user. See Errors for the error body and Common business-rule error codes for the full code lists.

Also note that Code 103 does not always mean a missing permission. Read Message first. See Errors.

Data scope patterns

These are the patterns integrations meet most often. Each table lists only operations whose requirements are documented.

Search operations: your allocations, or all tasks with a privilege

The search operations below return results from the tasks the user is allocated to. To search across all tasks, send searchAll=true. This needs the privilege 'all tasks' (RegistrationAllTasks). Without it, searchAll=true returns 403 with the message "User have no privilege to search all tasks.".

If your integration only needs the user's own work, omit searchAll. You then never get this 403.

Projects: the user's project privileges

Project data is scoped by the user's project privileges. A project privilege covers one of these sets of projects:

• all projects (ProjectAllProjects)
• all projects in the user's legal entity (ProjectAllInLegalEntityEmployees, when the account uses multiple legal entities)
• projects whose handling department is the user's department or below it (ProjectProjectsInUserDepartmentAndSubDepartment)
• projects where the user is project manager (ProjectProjectsWhereUserIsSetAsProjectManager)
• projects where the user is account manager (ProjectProjectsWhereUserIsSetAsAccountManager, when the account uses account managers)

The lists below are filtered: rows outside the user's project privileges are left out, and there is no 403.

The operations below check access and return 403 when the project is not covered. They need a project privilege with the ViewCreateEditDelete action that covers the project. For template projects, access to the system-administration page for project templates also qualifies.

On allocations, read access alone is not enough: GET /v1/allocation/{allocationID} also needs the ViewCreateEditDelete action.

Registering on behalf of other employees

Some registration operations take a UserID or address another user's registration. For the operations below, your own registrations need no registration privilege. For another user's, the user needs one of these registration privileges:

Which of these an operation accepts differs:

On the expense and mileage create operations, the target user must also exist and be active. That is checked first, with ErrorCode 37040 (not an existing user) or 37931 (inactive user).

Customers: all customers, or customers where you are account manager

POST /v1/customer/create needs one of two customer privileges:

• 'All customers' (CustomerAll), or
• 'Customers where user is account manager', with the caller set as the customer's primary account manager (PrimaryKAMID).

Otherwise the call returns 403 with the message "User has insufficient privileges to create customer".

Employees, competences and settings

Operations that return only your own data

These operations always return the token user's own data. To read another user's data with them, you need a token for that user.

GET /v2/search is scoped differently: each result category needs access to the matching TimeLog page and a matching area privilege.

Licences, modules and account features

Besides the user's privileges, an operation can depend on what the account has: its TimeLog product and licence plan, the user's licence, and the features switched on in TimeLog.

For example, the time registration operations listed above (DELETE /v1/time-registration/{id}, POST /v1/time-registration/update-time, the absence updates and POST /v1/time-registration/import) also check the product, licence-plan, module, feature and user-licence policies of the action. The expense and mileage creates and the employee-expense delete check the product, licence-plan and user-licence policies.

These are the requirements documented so far:

Recommendation: a dedicated integration user

Because every call runs as the token's user, the user you choose decides what your integration can do and see.

• Create a dedicated integration user. Do not use a person's own account. Actions are then attributed to the integration, and you can change its access without affecting a person.
• Give that user exactly the privileges the integration needs. Use the tables above to find them. For example, an integration that imports time for other users with POST /v1/time-registration/import needs 'all registrations'.
• Test with that user, not with an administrator. A user with broad privileges passes checks that your integration user may fail. Those failures then show up in production as 403 or as a privilege ErrorCode.
• Check the user's privileges from the API. GET /v1/privilege/user-privileges returns the privileges of the token's user.
• Expect lists to depend on the user. Lists such as GET /v1/project/get-all return fewer rows for a user with narrower privileges. Missing rows are not an error.

See also Authentication for choosing the token's user, and Errors for handling privilege failures.