7pace Timetracker API Important Information

API Authorization for 7pace Timetracker, Client API for tracking, PIN pairing API for Clients, OData Reporting API, using the API in your own project and building your own application with 7pace Timetracker 

7pace Timetracker API & Reporting Tutorial Webinar

7pace Timetracker Reporting API Documentation Version Links

API Authorization

Authorized Access in 7pace Timetracker cloud (Azure DevOps Services)

Authorized Access in 7pace Timetracker on-prem (Azure DevOps Server)

API Implementation

Client - API for Tracking

PIN - Pairing API for Clients

TimeEntryExport - OData Reporting API

Using 7pace Timetracker API in your own project

Building your own application with 7pace Timetracker

API Common Error Codes

API Request Limits Per Plan & Lifetime Policies

API Version Links 

We provide various versions of our API and the documentation for each. Use the links, below, to access the relevant 7pace Reporting API.

API 2.1 

Reporting API 3.0 and above

API Authorization

Authorized access in 7pace Timetracker for Azure DevOps Services cloud and on-prem have different implementations. Click below for the relevant approach:

1. Authorization Code Flow is the way that we initially obtain an access token.
   For more information on the OAuth 2.0 Authorization Code Flow, see section 4.1 of the OAuth 2.0 specification: https://tools.ietf.org/html/rfc6749#section-4.1. The first step is different from the specification: instead of relying on User-Agent (web browser), we use PIN codes to validate a user.
2. RefreshTokens is the way we update expired access tokens.
   For more information on Refresh Tokens, see section 1.5: https://tools.ietf.org/html/rfc6749#section-1.5.

Note: Please use OpenApi as client_id to authorize any external application.

Authorized Access in 7pace Timetracker on-prem (Azure DevOps Server)

To use 7pace Timetracker REST/SignalR API in on-prem environment you don’t need tokens. All requests must be authorized with NTLM authorization.

Reporting API for DevOps Server on-prem

*Please note there is an ongoing issue with Tableau. Please use NTLM authentication.

Using 7pace Timetracker API in Your Own Project

To help you access 7pace Timetracker's data through our API, we've provided the source code of a simple application that demonstrates basic 7pace Timetracker API usage in GitHub.

You can get more information about our API model and parameters at Settings -> Reporting and API -> Reporting and REST API -> 7pace Timetracker API Reference.

Building your own application with 7pace Timetracker

7pace Timetracker allows you to build custom applications that fully meet the requirements of your organization with the Client API. It is up to you what functionality this application should include. This could be integration between any kind of software you currently have and 7pace Timetracker or new stand-alone applications based on just the 7pace Timetracker API.

Requirements

• A basic level of experience in any programming language.
• Access to a computer running Windows, Linux or Mac OS.

Platform Overview

7pace Timetracker is lightweight and simple. It's built on JSON and OData, so you can use it with any language or platform that supports HTTP requests or SignalR (including .NET, JavaScript or PHP). The 7pace Timetracker service runs on a server (on-premise for Timetracker for DevOps Server or the Microsoft cloud for Timetracker for DevOps Services) and provides the following set of APIs for developers: RESTful API, OData API, and SignalR.

Getting Started

To start developing your own application, learn how our API works in more detail at: 7pace Timetracker API Reference.

DevOps Server (on-prem) Workflow

For pairing with DevOps Services, we do not have any tokens. Timetracker uses NTLM auth for API endpoints and impersonates calls to DevOps Server with this data.

The only thing we need is the address of the 7pace Timetracker application. 

If you know your 7pace Timetracker URI, just use %timetracker_address%/api address to API.

If you only know the DevOps Server URI and want to find the 7pace Timetracker address, please use this procedure:

1. User enters AD credentials to connect to DevOps Server.

2. User enters DevOps Server URL with collection.

3. 7pace Timetracker performs GET request to %CollectionName%/_apis/Contribution/InstalledApps/.

4. In the returned JSON, find extension with:

"extensionId": “TimetrackerOnPremises”,
“extensionName”: “Timetracker”,
“publisherId”: “7pace”

5. Use baseUri from the found extension to validate access to GET /api/tracking/client/latest?api-version=2. 

DevOps Services (cloud) Workflow

You can authorize your application in 7pace Timetracker using two options:

A. Use a Reporting API token. Add the "Authorization" header to any 7pace Timetracker API request with value "Bearer %TOKEN%"

The main downside of this approach is that this token is valid for just one (1) year and you can only refresh it by using the 7pace Timetracker Web UI. If you're writing automation, you should use the next option and get proper access and use refresh tokens for your application.

B. Use OAuth-base flow for obtaining authorization tokens:

1. Perform a POST request to /api/pin/create?api-version=2. Returned object contains a PIN and security code - the PIN should be demonstrated to you. Now, go to the 7pace Timetracker Web UI to Settings -> Reporting & REST API -> select tab "REST API" -> Connect to an app using PIN. Enter your PIN here. Please note that your PIN is valid for one (1)minute. After your PIN has been entered, this security code is now bound to you, the specific user, and the rest of the OAuth flow can now be executed.

2.  Check if the PIN is validated by performing GET

/api/pin/status/{security_code}?api-version=2.
If the PIN is validated, the server will respond with “validated” as the PIN state.

5. Now you can request a token by performing a POST request to /token endpoint with data described below in "Request definition".

6. If the server returns "Invalid" as the state, request a new token by restarting the whole flow.

Request definition:

Headers:

Content-Type: application/x-www-form-urlencoded

Body:

client_id=OpenApi&grant_type=authorization_code&code=%security_code%

Server will return the object with access and refresh tokens.

IMPORTANT: A token’s lifetime is one (1) hour (3600 seconds); Refresh Token is valid for one (1) year (129600 seconds).

Diagram of the process described, above:

Refreshing tokens:

To obtain a new token with “Refresh Token”, perform this request:
POST
/token
Headers:
Content-Type: application/x-www-form-urlencoded
Body:
client_id=OpenApi&grant_type=refresh_token&refresh_token=%your_refresh_token%

Use access token by adding "Authorization" header with value "Bearer %TOKEN%" when performing any requests to the 7pace Timetracker API.

NB:

A token is valid for SignalR until it disconnects.

Therefore, even an outdated token maintains a valid SignalR connection.

API Common Error Codes

Introduction

In newly-introduced CRUD API, our team now starting classification of errors and putting together all possible states and responses of API and system. 

Each error will have it's own unique and constant code that you can relate to.

System state errors

• UnexpectedError - Unexpected error occurred. 
  General unhanded error during internal logic execution. It will contain additional info with original error and original stack trace.
• UnknownError - Unknown error occurred. See additional details for more information
  Represents an error that  has occurred outside of the Timetracker logic environment. This usually happens when server or cloud issues are present.
• ApiDisabled - API is disabled due account maintenance
  When account is migrating between instances of our application API is disabled to maintain data integrity.
• LicenseReadOnly - System in a read only state (check your license)
  For On-Premises (TFS) only. If license is not valid or expired - API will be disabled as well as main system.
• ActivityTypeDisabled - Activity type feature is not enabled
  Error will affect only "/activityTypes/{id}" endpoint if you try to get any specific Activity Type by Id when feature is disabled.
• ApiVersionError - API Version not specified, or path do not support required version, or supplied parameters has invalid values
  Due the way our system handles versioning, it will fail with version error even if you're specifying correct version of API for endpoint, but supplied incorrect types of parameters (eg. not valid GUID). Recheck your request.
• QuoteExceededError - Quota exceeded
  You're making too many requests. Current quota is dependent on plan type per organization. Check header "Retry-After" for value in seconds when block will be lifted.
• UnauthorizedError - Unauthorized
  You're using invalid authorization credentials or not provided any authorization info. Check here for authorization options, depending on if you're using cloud or on-premise.
• AccessDenied - Access denied (you don't have enough rights?)
  You've been successfully authorized, but you don't have enough rights to execute requested resource.

Validation errors

• EntityNotFound - Entity not found
  Occurs when requested by Id entity is not present in Database.
• WorkItemIdOrCommentRequired - WorkItemId or Comment required
  Occurs when creating or updating worklog. It must have either comment or be associated with Work Item.  
• LengthIsRequired - Length is required
  Occurs when creating or updating worklog. It must have length and it cannot be automatically set.
• LengthMustBePositive - Length must be greater than 0
  Occurs when creating or updating worklog. It must have length as positive integer value.
• FutureCheckFailed - Adding worklogs in a future not allowed by settings
  Occurs when creating or updating worklog. Managed by setting "Prevent Time Tracking Beyond Present Day". If Timestamp of a worklog is not meeting selected requirements, this error is raised.
• ApprovalStateFailed - Selected date is locked for editing by approval
  Occurs when creating, updating or deleting worklog. If date of worklog is within approved interval, editing is restricted.
• NoRightsToWorkLogModification - Worklog cannot be modified by you
  Occurs when creating, updating or deleting worklog. If worklog doesn't belong to you and (when deleting) you don't have rights to delete it, error is raised.
• FilterWorkItemIdsCountExceeded - Filter work items ids count exceeding maximum allowed value (100)
  Occurs when requesting list of worklogs and using filter "$workItemIds". If amount of Ids is exceeding maximum allowed value (100), error is raised.
• DbValidationError - Error while committing entity to database
  Occurs when creating, updating or deleting worklog. General error if entity is failing validation in Database. Will contain additional information about errors.

API Request Limits and Lifetime Policies

Depending on the subscription/plan you have with 7pace Timetracker, there may be limits on the number of API requests that you and your team are allowed. "Throttling" is the process of limiting the number of requests you can submit to a given operation within a given amount of time.

If you have received a message with a "code 429" that says, "The request has been cancelled because your API usage was exceeded", you will have to wait before sending a new request.

Depending on your Timetracker plan type, there may be API request limits. 7pace Timetracker's API also contains limitations based on your plan. For more information, click here. 

Abuse or excessively frequent requests to 7pace Timetracker via the API may result in the temporary or permanent suspension or throttling of your Account's access to the API. 7pace will determine abuse or excessive usage of the API and will make a reasonable attempt to warn you via email prior to suspension or throttling. Throttling can occur if there is excessive usage of the APIs. If you have any additional questions regarding API usage within your team, please contact us at support@7pace.com

Plan	Per   Hour	Per   Minute
Free	50	5
Start	100	10
Team/Ultimate	500	60

Throttling will be triggered with the usage outlined in the table, above

Stable API Policies

The stable API version for Timetracker is 2.1 and 3.1.

We guarantee that the API version will be not be affected and will continue working in productive mode for the last two major releases, with the possibility of deprecation after the second major update.

e.g. If API v2.1 was introduced in 7pace Timetracker 4, it will continue working in 7pace Timetracker 4 and 7pace Timetracker 5, but could be deprecated in Timetracker 6. However, the API will continue to work with “deprecated” header response until v7. Considering that the usual cadence of major updates is one (1) year, you can rely on the fact that the API won't change for the next two (2) years.

Beta API Policies

As the "Beta API" is actively developed, it might change at any time, including structural changes, changes in models, responses and URLs until it reaches a stable state (indicated by removed “-beta” flag in the version number).

In some cases, it could also contain specific improvements and fixes that are not present in the production version.