Getting started

Hi, nice to see you.

Let’s build awesome things.

This is the developer guide for the awork API, which allows developers to access entities and business logic of awork. We’re glad you’re here, and we hope that the documentation will help you build something awesome.

At HQLabs we do our best to build a powerful and easy-to-use public API. What does that mean to you? It means that if you see something happening in the awork web app, you can probably do that same thing via the API.

Before you get started you’ll need to follow the following steps:

Yes No Suggest edit
Last updated on 19. Februar 2019

API Description

Request Structure

The awork API is available via HTTPS endpoints and follows a RESTful address structure where resources are selected with text and Id segments in the URL. Typically Ids are in Guid format, i.e. a hexadecimal representation of a 128-bit integer separated by hyphens.
Other values are usually sent in the body of the request, which are only accepted in JSON format (content type: application/json).

The URL of our API is composed of three different segments:

  • The base URL: https://api.awork.io/api/v1
  • The content/resource url: /users
  • The filter query (optional):?page=1&pageSize=50

The complete URL can look like this: https://api.awork.io/api/v1/users?page=1&pageSize=50

CRUD Calls vs. Business Operations

Most API calls contain simple CRUD endpoints to handle the data manipulation for that particular entity. In some cases the default POST, PUT or DELETE routes are replaced by so-called business operations. The reason for this separation is that actions do not only manipulation the entity itself, but also affect other entities or even trigger further actions, workflows or events in other parts in awork. An example for this would be an automatic task creation triggered by the status change of a project.

Business operations can be identified by an additional segment in the URL, which usually begins with a verb. For Example:

  • setArchived
  • removeProjectMember
  • renameTag
  • setStatus
  • etc.

Deleted vs. Archived

In some cases, deleting an object can have unintended side effects because of dependencies of other objects. An example for this is the project type. Once you’ve linked projects to a particular type, it can be complicated to delete the type because you will have to move all projects using that type to another type. For these cases you can set that particular object to archived, which is a form of soft-deletion. Once flagged as archived, it can no longer be used, but still exists for legacy data it is already linked to.

Error Handling

In case a request to our API fails, the return value of the endpoints follows standard HTTP status code conventions. A detailed reason can be found in the response. Common codes indicating a client error are 400 (Bad Request) & 404 (Not Found). To give some further information on the cause of the error the API also returns a standardized error object in the response body:

{
  "code""validation-failed"
  "description""The model sent in the request is invalid. See the validation errors for details."
  "link""https://developers.awork.io/#response-types",
 "space""On Venus a day is longer than a year.",
 "details": [ 
    "Some more details about the error can go here.",
    "Or here."
  ]
  "validationErrors": [ 
    {
      "property""Name"
      "message""'Name' should not be empty."
    }
  ]
}
  • Code: These string error-codes are constants indicating the exact misbehaviour. The following codes are in use:

Code
Description
teamid-missing
The request is missing a valid team id. Most likely your token is invalid.
not-foundThe requested resource could not be located.
entity-archivedThe request tried to perform an operation with an archived entity.
duplication-violationA property that requires a unique value detected a duplication.
database-commitThe commit to the database failed. Your changes have not been commited!
concurrency-violation
Concurrent processes changed data and created conflicts in the process.
date-dependencyTwo or more date values are in violation with each other (e.g. start date after due date).
date-out-of-range
A single date value is not in its validity range (e.g. birth date in the future).
value-out-of-rangeA value is not in its defined range of validity (e.g. negative prices).
invalid-operationThe request would have caused an illegal data state.
invalid-model
The body of the request is invalid or empty.
validation-failed
The model validation of the request failed.
server-errorAn internal error occured.
already-exist-errorThe request adds an entity which already exists.
invalid-filter-or-order
The request contains an invalid filter or sort statement.
illegal-property-transition
The request would cause a value transition which is not allowed.
unauthorizedThe owner of the request has insufficient permissions.
invalid-batch-operationThe request for a batch operations is invalid.
deactivated-userThe request tried to perform an operation with a deactivated user.
request-body-too-largeThe uploaded file exceeds the allowed size limit
insufficient-subscription-levelYour team does not have the required subscription level to use this feature. Upgrade to a higher plan.
insufficient-seatsYour team does not have enough remaining seats while trying to invite or activate users.

  • Description: A human-readable explanation for the cause of the error.
    For example:

    • Identity cannot be invited to this team. The identity is already part of the team.
    • The password is too simple
  • Space: An interesting fact about space.
  • Link: A link to the corresponding documentation.
  • Details: Further explanations or hints on fixing the request.
  • ValidationErrors: If the model validation failed, all violations are listed here.

HTTP Status Codes

On each request to our API you get a response with a HTTP status code that indicates if it was successful.

Success Status Codes


GET           200 (OK) including the object(s)
POST          200 (OK) including the newly created object
              202 (Accepted) for batch or background operations
              204 (No content) for business operations without a return value
PUT           200 (OK) including the updated object
DELETE        204 (No content)

Client Failure Status Codes


400 (Bad request)   When the request model is invalid or the operation is not allowed
401 (Unauthorized)  When the requesting user is lacking the necessary permissions for the request
404 (Not found)     When a requested resource does not exist

Pagination

Why pagination?

To obtain data, you have to make calls to the REST API. The response of such a call can lead to a huge data set. To avoid this, awork smartly paginates the responses so that they are flexible and easier for users to handle.
For example, if you get all the projects, the response could end up with hundreds or thousands of projects and their details which, certainly creates a bad experience for your users. To avoid this, a built-in default limit on the server response is set which varies on which data you are trying to retrieve. The limit is configurable, i.e. you can specify the number of results that you would like to receive from the server.

How to configure the limit?

You can set the number of items that you would like to get from the API via two properties: page and pageSize.

For example, if you want to get 50 users you would end up making a call with the following url: https://api.awork.io/api/v1/users?page=1&pageSize=50.

NameTypeDescription
pageinteger (query)The number of the current page.
pageSizeinteger (query)The number of items on this page.
sortBystring (query)The property to define on which property the items sorted by.
orderstring (query)Define if the items are ordered by ascending or descending.

How to find the total number of results?

When you make a call to retrieve the users from the API, you get the response as well as its headers. The headers of the response contain a property named “aw-totalitems”, which provides the information about the maximum retrievable results.

Any smart options?

You can sort as well as filter the data that you would like to get from the API by specifying the properties sortby and order.

Filter

The API uses a subset of the query syntax from ODATA, so most of the common queries will be compatible.

Operator DescriptionExample
eqThe eq operator filters and returns the items which matches the expression.https://awork.io/api/v1/users?filterby=firstname eq 'Neil'
neThe ne operator filters and returns the items which do not match the expression.https://awork.io/api/v1/users?filterby=firstname ne 'Neil'
endswithThe endswith operator filters and returns the items which end with the string.https://awork.io/api/v1/users?filterby=endswith(FirstName, 'Neil' )
startswithThe startswith operator filters and returns the items which start with the string.https://awork.io/api/v1/users?filterby=startswith(FirstName, 'Neil' )
contains.The contains operator filters and returns the items which contain the stringhttps://awork.io/api/v1/users?filterby=substringof('Neil',FirstName)
gtThe gt operator filters and returns the items which are greater than the expression.https://awork.io/api/v1/users?filterby=birthDate gt datetime'2018-04-03T00:00'
ltThe lt operator filters and returns the items which are less than the expression.https://awork.io/api/v1/users?filterby=birthDate lt datetime'2018-04-03T00:00'
leThe le operator filters and returns the items which are less than or equal to the expression.https://awork.io/api/v1/users?filterby=birthDate le datetime'2018-04-03T00:00'
geThe ge operator filters and returns the items which are greater than or equal to the expression.https://awork.io/api/v1/users?filterby=birthDate ge datetime'2018-04-03T00:00'
anyThe any operator iterates through the main entity (Project), executes the condition and returns the filtered list of projects whose any member with the first name Neil.https://awork.io/api/v1/projects?filterby=members/any(p: p\FirstName eq 'Neil')
allThe all operator iterates through the main entity (Project), and returns the filtered list of projects where all members have the first name Neil.https://awork.io/api/v1/projects?filter=members/all(p: p\FristName eq 'Neil')
countThe count operator iterates through the main entity (Project) and returns the filtered list of projects that have less than 10 members.https://awork.io/api/v1/projects?filter=members/count() lt 10
minThe min operator iterates through the time entries of a projects, computes the minimum tracked time on the project and returns the filtered list if the minimum value is greater than one hour.https://awork.io/api/v1/projects/timetrackings?filter=duration/min() gt 3600
maxThe max operator iterates through the time entries of a projects, computes the maximum tracked time on the project and returns the filtered list if the maximum value is equal to one hour.https://awork.io/api/v1/projects/timetrackings?filter=duration/max() eq 3600
sumThe sum operator iterates through the time entries of a project, computes the sum and returns the filtered list of projects where the sum is greater than one hour.https://awork.io/api/v1/projects/timetrackings?filter=duration/sum() gt 3600
averageThe average operator iterates through the time entries of a projects, computes the average and returns the filtered list of projects where the average is greater than one hour.https://awork.io/api/v1/projects/timetrackings?filter=duration/average() gt 3600

Tags

Tags are small strings of additional information that can be added to certain entities. Tags are simple strings with no additional data, but they help to categorize the entities and it is easier to find them via uplink.

Yes No Suggest edit
Last updated on 3. Juni 2019

Authentication

Basics

The API uses the OAuth 2.0 authentication framework to allow external applications to access the team data.

Client Application

A client application needs to be registered before you can make API calls. Go to the team settings panel in awork and add a new client application. You will be asked to provide a unique name and a display name for your client. You will receive a client secret in return.

The client secret is only shown while creating the client application! It can be regenerated, but all clients will lose access when their tokens expire.

Client Id

The client_id is used to identify your client application. After you registered a client application, you’ll find the client_id in the list of client applications in the team settings panel.

Client Secret

The client_secret is generated in the client applications section of awork. It is located next to the client_id in the team settings page. The secret will be used to authenticate your client application when you request a token.

The client secret is only displayed when creating the client application! It can be regenerated, but all clients will lose access when their tokens expire.

Scopes

The OAuth 2.0 authentication flow uses scopes to define which rights are granted to the application by the user. Scopes are sent as a space separated list. The API currently supports these scopes:

  • full_access: read and write access to all resources.
  • offline_access: continued access, issues a refresh token.

Tokens

Access Token

The Access Token is used to authenticate yourself with the API resources. It needs to be included in every request to the API. Each user has to use their own unique Access Token, since such tokens are only valid for the associated user. Also, Access Tokens are valid for one team only. If the client application wants to access multiple teams, it needs to request separate tokens. The token is usually valid for a few days only.

Refresh Token

The Refresh Token is used to get a new Access Token, once it has expired. A Refresh Token only expires when the user manually revokes access for the client application.

Authorization Code

The Authorization Code is a transitory code to retrieve an Access Token. It should not be stored in the client application.

Endpoints

The OAuth endpoints are required to get an Access Token and exchange a Refresh Token for a new Access Token:

Authorization Endpoint: /accounts/authorize may be used to initially retrieve an Authorization Code.

Token Endpoint: /accounts/token may be used to retrieve an Access Token from either an Authorization Code or a Refresh Token.

Authorization Code Flow

Authorization Request

The client constructs the request URI by adding the following parameters to the query string of the authorization endpoint URI using the application/x-www-form-urlencoded format. The client directs the user to the constructed URI using a browser window. The user is prompted to log in, enter her or his username and password, and grant the requested permissions to the client application. If the user is part of several teams in awork, the user needs to select the team before authorizing the application.

Parameter:

  • client_id: The client Id of the client application. Required.
  • redirect_uri: The user will be redirected to a custom URI after the access was granted. Needs to be the same as specified when registering the client application. Required.
  • scope: A space-separated list of API scopes. Required.
  • state: An arbitrary state string that helps the client application to identify the request. Optional.
GET https://app.awork.io/api/v1/accounts/authorize?
    client_id={client_id}&
    response_type=code&
    grant_type=authorization_code&
    redirect_uri={redirect_uri}&
    state={state}&
    scope={scope}

Note: The generated URL needs to be opened in a browser window. the user has to log in to authorize the application.

All query parameters (especially the redirect_uri) may be properly URL-encoded.

User Authentication

The user logs in and grants or revokes the authorization request.

Authorization Response

If the user grants the authorization request, the authorization server issues an authorization code and delivers it to the client by adding the following parameters to the query string of the redirection URI using the application/x-www-form-urlencodedformat.

Parameter:

  • redirect_uri: The previously specified redirect URI.
  • code: The authentication code that can be exchanged for a token later.
  • state: The same arbitrary state string that the client application passed in the authorization request earlier.
302 Found
{redirect_uri}?code={code}&state={state}

Access Token Request

If the client application has been successfully authorized, it sends a request with the following parameters in the body to the token endpoint using the application/x-www-form-urlencoded format.

Parameter:

  • code: The code that was received in the previous authorization response. Required.
  • redirect_uri: The previously specified redirect URI. Required.
  • client_id: The client Id of the client application. Required.
  • client_secret: The client secret of the client application. Required.

Note: To build a proper HTTP Authorization header for Basic Access Authentication, you need to encode your client_id and client_secret using Base64, and add it to the Authorization header as follows: Authorization: Basic Base64({AppId}:{AppSecret})

POST https://app.awork.io/api/v1/accounts/token
redirect_uri={redirect_uri}
  &grant_type=authorization_code
  &code={code}
Authorization: Basic Base64({client_id}:{client_secret})

Note: All query parameters (especially the redirect_uri) should be properly URL-encoded.

Access Token Response

If the access token request is valid and authorized, the authorization server issues an Access Token and Refresh Token. If the request failed or is invalid, the authorization server returns an error response.

{
   "access_token""eyJhbGciOiJ...",  // The Access Token used for authorization.
   "token_type""Bearer",            // The token type, usually 'Bearer'.
   "resource""awork.io",          // The resource that granted the token.
   "expires_in": 86400,               // The expiration time of the token, in seconds.
   "refresh_token""eyJhbGciOiJ..."// The refresh token to get a new access token, if requested.
}

After receiving the Access Token, you can use it to request resources from the API.

Resource Request

To receive resources from the API, add the Access Token to the Authorization header in the following form:

Authorization: Bearer {access_token}

Note: Access Tokens expires and needs to be refreshed with the Refresh Token.

Examples

Postman

In Postman, open a new Request tab, click on Authorization and select OAuth 2.0 in the dropdown. Click “Get New Access Token” and fill in the details as shown below. Replace the Callback URL, Client ID, Client Secret and optionally State with your values as described above.

Yes No Suggest edit
Last updated on 28. Mai 2019

Permissions

Basics

The Permissions allow you to define user access to certain features.
To simplify this, we use a role-based approach that allows a collection of users to be handled by the same collection of permissions.

Permissions

In awork we have two permissions: read and manage. With the read permissions of a feature, you have access to all GET endpoints which are related to this feature.
To get access to the POST,PUT, DELETE and Business Operation endpoints, manage permissions for this feature is required.

Features

A feature groups a functional area in awork to which permissions can be assigned. This simplifies configuration considerably.

With the permission on a function you not only get access to one API endpoint but to all those who belong to this functional area.
Let’s take the project-planning data feature as an example. This will give you access to the project task endpoints. You also get access to the comments endpoints, which allows you to leave comments on project tasks.

Roles

Roles connect users and features. They define which users are authorized to use the functions of the role.
However, there is a difference between standard and project roles. A regular role defines the rights of a user in the entire application.
Each user must belong to only one role.
Project roles define the permissions of a user (project member) in a project.

In awork there is always one admin role and it must always contain at least one user. The users in the admin role have access to all features and can manage permissions for other users.

 

Yes No Suggest edit
Last updated on 1. Februar 2019

Accounts

The registration data used to login with awork is referred to as an account. An account is associated with a unique email address and password that the user provided when logging in to his or her awork account.

A user can work in several teams with the same account (and also the same access data). As shown below, the account of [email protected]astronauts.com is part of two teams, Moon and Mars. Tommy uses the same email address and credentials to access both teams. While there is only one account, each team has a user entity associated with the account. A user entity is always team-specific.

 

The account only contains basic account information. More details about the user in each team can be retrieved and edited at the /user endpoints.

Client applications are important for the external login flow used by your applications. These endpoints allow you to administrate the client applications managed by your team. Check out the Authentication guide to learn more about client applications.

Permissions

In order to make permission changes, the user has to be in an administrator role.

If you want to try out these endpoints, click the following button and get all the endpoints as a collection for Postman.

Yes No Suggest edit
Last updated on 16. August 2019

ActivityLogs

Activities show you which changes have been made to an object and by whom.

Activities can be viewed from the main data like projects and tasks.

Permissions

To retrieve the activities, you need read permissions on the master-data feature of the respective entity.

If you want to try out these endpoints, click the following button and get all the endpoints as a collection for Postman.

Yes No Suggest edit
Last updated on 16. August 2019

Comments

You can leave comments on all main objects. Comments can help to clarify procedures and questions or provide additional information.
Files can also be attached to each comment.
However, these files are uploaded via the Files-API. The file is automatically linked to the comment, therefore the EntityId, which must be set when the file is uploaded, has to contain the comment’s Id.

Permissions

To create and edit comments, permissions are required on the respective object to which the comment belongs. These are the read permissions on the master-data features of the respective entity.
In the projects example, this means that the user needs read permissions on the project-master-data feature.
A special case are comments on tasks. The user must be either the task’s assignee or have read permissions on the project-planning-data feature to comment on project tasks.

When deleting comments, please note that this can only be done by the creator of the comment.

If you want to try out these endpoints, click the following button and get all the endpoints as a collection for Postman.

Yes No Suggest edit
Last updated on 16. August 2019

Companies

Companies – aka ‘Clients’ in awork – represent all groups that relate to real companies, such as customers, partners, suppliers, competitors etc. Its main purpose is to present the most important information, including contact data, and serve as a link to various other types of data such as projects or tasks. Contact information is managed as a separate entity, therefore each company can have multiple contacts.

Permissions

To receive data or to create companies, read permissions on the company-master-data feature are required.

If the user also has permissions on the feature company-manage-config, then this user is authorized to edit Company Types and Company Number Schemas. Whether the user is allowed to rename the tags of companies also depends on this permission.

If you want to try out these endpoints, click the following button and get all the endpoints as a collection for Postman.

Yes No Suggest edit
Last updated on 16. August 2019

Files

We differentiates between the content of a file and its metadata. While you can retrieve the metadata like any other object of the API, the content is available separately on dedicated endpoints. When you upload new files, this distinction is not made and the file is created by a single multipart/form-data POST request with all the metadata and content in the body of the request.

Another convenient feature is that we create different versions of your files. You can update the metadata and content of an existing file without losing the original file. We automatically create a new version in this case and link it to the existing version.

For images, they are special API endpoints that allow you to automatically scale and crop images as needed.

Shared Files

Shared files are files that awork provides for public access. To retrieve a file, a token generated by awork is necessary.

Temporary Files

Temporary files are files that have no current association with an entity and are not global. They allow you to upload files and assign them later to an entity. Temporary files are not visible in awork.

Permissions

Files are linked to a specific entity using an EntityId. This also determines whether the user is allowed to work with these files. Depending on the entity, permissions are required on the corresponding master-data feature. This also applies to the images.

It is also possible to work with files that do not have a link to an entity. These are available for all users in the team who have permissions to the feature files-master-data.

If you want to try out these endpoints, click the following button and get all the endpoints as a collection for Postman.

Yes No Suggest edit
Last updated on 16. August 2019

Permissions

Permissions give you control over the actions that users within a team can perform on the API endpoints. For this case, users are assigned to roles. In fact, every user is in exactly one role which defines their access rights. Teams can have multiple roles.

Certain actions require the special admin permission flag. To ensure every team has at least one administrator, the last user in the admin role cannot be removed from the role.

To change the permissions for a user you can either

  • change the permission set of the current role
  • or move the user to another role

Global roles define the global permissions for a user. Furthermore, project roles allow you to give users special permissions on a project member basis. The permissions regarding project roles are not directly linked to the user, but are assigned in combination with a project membership. You grant a certain set of additional permissions to a user that is assigned to a certain project role in a project. These permissions are only valid for that particular project.

Permissions

Permissions are a highly sensitive area in awork. Therefore only users with administration access or team-manage-config feature can edit permissions.

If you want to try out these endpoints, click the following button and get all the endpoints as a collection for Postman.

Yes No Suggest edit
Last updated on 16. August 2019

Projects

A project is a planned set of interrelated and sometimes dependent tasks that must be executed over a certain period of time, taking certain costs, resources and other constraints into consideration.
A project collects all necessary information to help you to get the project done.

Project Types

A project can be distinguished based on its type, for example design, development, testing, etc.
Creating a project type helps you to define a basic structure of your project. The type includes the statuses the project can take. You can define the available project roles for your members as well as task bundles. More information about task bundles are available in the Task-API.

Project Roles

Projects of different sizes have different requirements for the organization of people. A small project requires little organizational structure. However, more and more people are involved in large projects and it is important that people understand what is expected of them and what role they should play.

You can define project roles for each member of your team. Assigning a specific role to a member of your team helps him or her to get a better understanding of his or her tasks and work effectively towards a common goal. Project members of a certain role can also have special permissions on that project. See the project role permissions for more details.

Project Statuses

Each project goes through a lifecycle of events from start to end. Defining the project status is critical to enable your team members to communicate, organize, and work towards a common goal.
You can create statuses for each phase of your project.

Project Keys

Every project gets a unique key assigned. The tasks corresponding to this project will receive numbers based on the project key. This helps your users in identifying which project a task is assigned to.

Work Together

While creating a project, you must specify its type (mandatory). This project type has a set of project statuses, task bundles and project roles which are then assigned to that particular project.
Some of the other configurable options in a project are start date, a due date, customer, time budget, etc.

Permissions

To edit and read projects, you need permissions on the project-master-data feature.

In case a user should be able to edit the environment for projects, i.e. creating and editing Project Roles, Project Statuses, and Project Number Schemas, permissions are required on the project-manage-config feature. This feature also gives the user permission to change the project key.

If you want to try out these endpoints, click the following button and get all the endpoints as a collection for Postman.

Yes No Suggest edit
Last updated on 16. August 2019

Tasks

In awork you can organize your work with Tasks. In general a task can have one of two types.
Project tasks are the workload of a project with which you can plan. They follow a status workflow that you can define yourself. They are only “valid” if the project is in a status of a phase that is “in progress” and is therefore visible to the project members.
Private tasks are your personal to-dos. They also follow a status workflow that you can define yourself.

Smart task lists

Smart lists are custom filters regarding tasks that filter entities (Users, Projects, Tasks) or their specific properties (Statuses, Types, Tags). Users can share their smart lists by setting the IsShared property to true. When a smart list is shared, other users in the team either subscribe to or unsubscribe from it. Only the user who created the smart list has the permission to edit/delete it. If you are editing a shared smart list, you edit the filter for all users who have subscribed to the smart list.

Type of Work

With a Type of Work, you define the type of work for a task. A Type of Work is also used when you record your times. It will automatically use the same type of work as in the task, but you can also change it. It is possible to create any number of Types of Work.

Task Statuses

A task status defines a specific step that a task can go through. In general, a task status can be divided into four categories:

  • To do
  • In progress
  • Done
  • Stuck

For private tasks, four predefined task states are available to you. A task status of each category. The situation is different with Project Tasks. A task status belongs to a project, so a project task can also accept any task status from this project. In a project, you can create as many task statuses as you like. The important thing is, there must always be a status in the category ‘To do’ and ‘Done’.

Task Lists

A task list is a project-related grouping mechanism for tasks. They can be created manually or by templates. Tasks within a project can be in several lists in the same project. Users can also have private lists, in which case a task list is linked to a user id.

Task List Filters

You can filter your tasks on a wide variety of options. For example,
• based on task types
• based on timeline (Cont., Weekly and Monthly)
• based on the members of your project team
• based on done status
• based on priority
• based on due date
• based on the input filter query which the user has typed

Task Bundles

The task bundles are sets of predefined tasks and lists that can be added to a project. The user has the option to import a template for a project or assigning it to the project when it is created (if the task bundle is assigned to that particular project type).

Task Templates

Task templates contain basic details to create tasks of it.

Task List Templates

Task list template is basically a task list that can be added to a project. It contains multiple task templates that will create tasks in the project when added.

Permissions

The permissions needed to work with tasks depend on the task type. Secondly, whether the user is also the task’s assignee.
Regardless of the type of task, a user always has the right to edit a task if he or she is also assigned to the task.

Users who want to see and edit project tasks, but are not assigned, need permissions for the feature project-planning-data.
Only the assignee or owner has access to private tasks.

If you want to try out these endpoints, click the following button and get all the endpoints as a collection for Postman.

Yes No Suggest edit
Last updated on 16. August 2019

Teams

A team in awork is the group of people you work with. Every project you create and every file you upload is always linked to the team you work in.

When you work with the API, the authentication token determines which team you are currently working in. You can only access projects etc. of this team.

A user can work in several teams with the same account (and thus the same login credentials). As shown below, the account of [email protected] is part of two teams, Moon and Mars. Tommy uses the same email address and credentials to access both teams. While only one account exists, there is one user entity linked to the account in each team. A user entity is always team-specific.

 

A new team

When you create a new team, we set up various defaults. The unique subdomain is assigned automatically. We also create a set of default permissions, roles, task types and status for you so you can get started right away.

Adding users

A team usually consists of several users. When you create a new team via the API, your team is empty. Now you can invite users to your team.

To invite users, create new invitations, which will send an email to the user’s email address. To create an invitation, you need the role you want to assign the users to. For your convenience, we create a set of default roles when you create a new team.

Permissions

Only a user with administrator permissions is allowed to make changes to the team settings.

If you want to try out these endpoints, click the following button and get all the endpoints as a collection for Postman.

Yes No Suggest edit
Last updated on 16. August 2019

TimeTrackings

You can track times on tasks and projects.

awork offers various possibilities for tracking times.  A timing can be started when you begin an activity and stopped when you end it. It is also easy to log some times afterwards.

Time entries can be billed to the customer. To do this you have to mark it as billable and as isBilled if it has been billed. From this point on, the time entry can no longer be changed.

Timezone

We uses the IANA standard to identify the time zone. The time zone must be set for each tracked time so that we can convert the user’s time to UTC.
When time entries are queried, we returns the original time as well as the time in UTC. The client is responsible for the conversion to the times in the current viewer’s time zone.

Permissions

Permissions depend on the entity of the tracked time.
To create or receive a time entry for a project you need permissions on the feature project-timetracking. Regarding time entries of a task, however, the permissions depend on the type of the task.
For project tasks, project-planning-data permissions are required. If the user assigned to a task, they are allowed to create and edit time entries on that particular task.
When a time is tracked without an assignment to a certain project or task, no specific permissions are required. The creator of  time entry also has the right to change this time entry at any time.

To edit the time tracking types, the user needs permissions on the feature time-tracking-manage-config. These permissions are also needed to rename the tags of time entries.

If you want to try out these endpoints, click the following button and get all the endpoints as a collection for Postman.

Yes No Suggest edit
Last updated on 16. August 2019

Users

Users are your team members in awork.

A user can be part of several teams with the same account (and therefore the same login credentials). As shown below, the account of [email protected] is part of two teams, Moon and Mars. Tommy uses the same email address and credentials to access both teams. While only one account exists, there is one user entity in each team linked to the account. A user entity is always team-specific.

All actions and events in awork are associated to a user. Almost all entities have a CreatedBy and UpdatedBy property which refer to a user in the team.

User details

The detailed information of users includes status, contact details and tags. The status of a user is based on whether he or she has accepted the invitation, been activated or deactivated, etc. The contact details and tags are configurable by the user.

Activate/Deactivate

A user in awork can only be activated/deactivated by users with sufficient permissions to do so. An activated user is available throughout the entire system. A deactivated user will still be part of the team but cannot be assigned to any project/task and can no longer log in.

Contact Info

A user can have one or more contact info objects. These types are: Phone, Address, E-Mail, Messenger, Social profiles, etc. The following subtypes are available: Business, Private, Slack, etc.

Permissions

Each user has the permissions to change their own data at any time. However, as soon as the data of other users is visible or changeable, this requires permissions on the feature user-master-data.
To configure the environment for the users permissions on the feature user-manage-config are needed. This can be used to rename the user’s tags, for example.

If you want to try out these endpoints, click the following button and get all the endpoints as a collection for Postman.

Yes No Suggest edit
Last updated on 16. August 2019
Suggest Edit