TeamForge REST API

The TeamForge REST API documentation is provided in Swagger format and available to explore here online. Read about how to authenticate below.

View details »

EventQ REST API

TeamForge EventQ provides API for posting events from external tools as well as API for reporting and querying those events and their associations.

View details »

TeamForge SOAP/Event SDK

The SDK contains the JavaDoc and libraries needed for calling the TeamForge SOAP API as well as for writing Event Handlers that are triggered by events within TeamForge.

Download »

Subversion REST API

TeamForge provides a REST API for SVN that allows you to read information from a repository. If SVN is installed on a separate server then add /svn-rest/documentation to the base URL of your SVN server to view the documentation.

View details »

Git REST API

TeamForge provides a REST API for Git that allows you to read information from a repository. If Git is installed on a separate server then add /git/api/documentation to the base URL of your Git server to view the documentation.

View details »

TeamForge CLI

The TeamForge command line interface provides a robust set of tools to interact with your TeamForge site. You can download a binary package for your operating system and read the documentation on the CollabNet Labs website.

View details »

API Authentication and Access Tokens

Both the REST and SOAP API use OAuth 2.0 access tokens for authentication. Clients can obtain access tokens from the token endpoint which is located at /sf/auth/token.

Tokens

The tokens used by the TeamForge API are Bearer Tokens as specified in RFC 6750. This means that it is possible and allowed to share tokens among multiple clients or to have clients pass tokens to intermediate services, which then delegate tokens to TeamForge. TeamForge tokens use a standardized format, JSON Web Token (JWT). However, clients should consider access tokens to be opaque in order to guarantee compatibility with future TeamForge versions. It is the client's responsibility to protect the access token against theft. This means that access tokens should only be transmitted over SSL-secured connections and should not be persisted.

Grant Types

The token endpoint supports the Resource Owner Password Grant grant type as specified by RFC 6749. Any valid TeamForge user account can be used to obtain an access token.

Client IDs

The tokens endpoint requires a valid Client ID to be specified. Thirdparty software should use the preconfigured Client ID api-client. Tokens issued for this Client ID are valid for exactly one hour.

Scopes

Scopes can be used to restrict which services a token can be used for. Limiting the number of scopes decreases the potential damage that could occur in case an access token is stolen, so it is advisable to restrict the number of scopes to a minimum.

TeamForge currently supports the following list of scopes:

• urn:ctf:services:ctf - needed to call the TeamForge REST API
• urn:ctf:services:svn - needed to call the Subversion REST API
• urn:ctf:services:gerrit - needed to call the Git REST API
• urn:ctf:services:soap60 - needed to call the TeamForge SOAP API or the EventQ Reporting API

Passing access tokens to the API

In compliance with the Bearer Tokens specification (RFC 6750), TeamForge expects access tokens to be passed in the Authorization header:

            GET /resource HTTP/1.1
            Host: teamforge.example.com
            Authorization: Bearer SAksa921hjsi...
           

Example for requesting a token

Here is an example bash script that shows how to obtain a token:

           #!/usr/bin/env bash

           # Base URL of TeamForge site.
           site_url="https://teamforge.example.com"

           # TeamForge authentication credentials.
           username="foo"
           password="bar"

           # Requested scope (all)
           scope="urn:ctf:services:ctf urn:ctf:services:svn urn:ctf:services:gerrit urn:ctf:services:soap60"

           curl -d "grant_type=password&client_id=api-client&scope=$scope&username=$username&password=$password" $site_url/sf/auth/token

          

Breaking down this example script, you can see it is sending an HTTP POST request to the /sf/auth/token endpoint, and the content of the request body contains the following data:

• grant_type=password - indicates you are providing username and password. This is the only supported option.
• client_id=api-client - indicates it is an API client requesting a token. This is the only supported option.
• scope= ... - space-separated list of requested scopes.
• username=value&password=value - the valid TeamForge user credentials

A successful response will return the HTTP 200 status code and the response body will contain something like this:

           {
             "access_token": "eyJraWQiOiIxIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJhZG1pbiIsImF1ZCI...",
             "token_type": "Bearer"
           }