Authentication

To access REST Services you must be authenticated as an active Targetprocess user or as the System User. There is no anonymous access allowed. Requester accounts are not granted access to the API.

Targetprocess REST API client can use cookie, basic or token authentication modes.

HTTP 401 status code (401: Unauthorized) is returned if authentication is failed.

Token Authentication

Token authentication mode uses a custom security token provided with URL. Using the token, your REST client application will obtain the same projects and teams membership and security permissions that the user who is owner of the token has.

Two different types of tokens are available and supported now in Targetprocess:

Personal Access Tokens set within user interface

📘

Supported in Targetprocess v3.8.2+

In earlier versions only tokens generated by /api/v1/Authentication service can be used.

Obtain a token

The tokens can be added under Access Tokens tab in personal details. Administrators cannot add tokens for other users.

You can use them as long as you want. When the token is not needed anymore it can be deleted.

For security reason a new token is shown and can be copied only after its creation. You can delete old tokens you do not remember them. And you can generate new tokens whenever needed.

You can track tokens usage directly from the same tab.

Use token

The received token could be used with any REST service by adding access_token={token} request parameter to URI.

GET /api/v1/UserStories/?access_token=YWRtaW46QUFBMEEwQTAwMEFBQTBBMDBBMEEwQTBBMEEwMEFBMDA=

Tokens generated by /Authentication service

Obtain a token

To obtain a token, you must be logged in within Targetprocess. To get a security token, you need to query the Authentication REST service via URI below:

GET /api/v1/Authentication

And you will receive the token for yourself:

<Authentication Token="YWRtaW46OTRDRDg2Qzg1NjgzQUZDMzg3Qjg2QTVERTAxRTZEQzY="/>

The token is valid as long as a user does not change their login or password. If a user changes his login and/or password then the new token is generated for him automatically.

The token for an active user is always active as well.

Authentication service supports both XML and JSON formats.

Use token

The received token could be used with any REST service by adding token={token} request parameter to URI.

GET /api/v1/UserStories/?token=YWRtaW46QUFBMEEwQTAwMEFBQTBBMDBBMEEwQTBBMEEwMEFBMDA=

Get Token for other users and System User

Administrators in Targetprocess can also obtain a token for other users. Pass their login name in parameter:

GET /api/v1/Authentication?login=mwhite

Token for System user is obtained the same way:

GET /api/v1/Authentication?login=System

This user has the same permissions in the account like any Administrator user has. With this token any data modifications can be performed.

Cookie Authentication

If you are logged in to a Targetprocess user account, then your web browser remembers your user login within cookies. When you try to reach the /api/v1/UserStories/ resource using the address bar of your browser, a GET request to REST API is sent and your cookie is used for authentication.

The same thing happens by default if you use REST API services from Mashups code. The cookie of the logged in Targetprocess user is used for authentication.

It is possible to use cookies from the web browser when you post REST API requests with a web browser plugin. For example, in the Chrome web browser there is plugin named Advanced REST Client. To obtain a cookie, toggle on 'Use XHR' mode in REST client settings. Additionally, the ARC cookie exchange plugin should be installed.

Basic Authentication

❗️

Basic Authentication is not recommended for instances that use Single Sign On and/or Frontdoor as user login method. Instead, use token or access_token for authentication.

To use Basic Authentication, you need to send an Authorization: Basic header with every request. For example, if you want to be authenticated as admin:admin (login:password), you should send the following request:

GET /api/v1/UserStories/ HTTP/1.1
Authorization: Basic YWRtaW46YWRtaW4=

🚧

YWRtaW46YWRtaW4= key is a Base64 encoded login and password values for admin:admin which are default credentials for any new Targetprocess account owner.

You can generate such a key online.

When you encode a login:password pair, please make sure you don't have any extra spaces or carriage return / line break symbols at the beginning or end of the copy-pasted line.

DO NOT use Basic Authentication if the communication channel is not secured via HTTPS, since transmitted credentials are encoded with Base64, not encrypted or hashed.

Using cURL tool you don't need to encode the login and password for Basic authentication, cURL does it for you automatically.

curl --user login:password /api/v1/userstories/

Also you can use a special function in your programming language.

For example, in .NET / C# it will look like that:

var webClient = new WebClient();
webClient.Credentials = new NetworkCredential("admin", "admin");

To consume the REST service from Ruby, you may use HTTParty gem.

class UserStoryResource
  include HTTParty
  base_uri 'testaccount.tpondemand.com'
  format :xml
  def initialize(u, p)
    @auth = {:username => u, :password => p}
  end
  def all_stories(options={})
    options.merge!({:basic_auth => @auth})
    self.class.get("/api/v1/UserStories/", options)
  end
end
...
storyResource = UserStoryResource.new('admin', 'admin')
stories = storyResource.all_stories

Basic Authentication mode is supported for System User when login form is enabled. When login form is disabled in Single Sign-On settings then this type of authentication becomes blocked. Use token-based authentication instead.

Retrieve logged user details using API

After successful authentication, you can I get details about logged user ID and role. Query LoggedUser resource by the following path:

/api/v1/users/LoggedUser/

It will give you details about Logged User.

<User ResourceType="User" Id="334">
  <Kind>User</Kind>
  <FirstName>Teddy</FirstName>
  <LastName>Bear</LastName>
  <Email>[email protected]</Email>
  <Login>xxx</Login>
  <CreateDate>2006-10-02T16:19:42</CreateDate>
  <ModifyDate>2016-11-17T00:01:16</ModifyDate>
  <DeleteDate nil="true"/>
  <IsActive>true</IsActive>
  <IsAdministrator>true</IsAdministrator>
  <LastLoginDate>2016-11-17T00:00:00</LastLoginDate>
  <WeeklyAvailableHours>20.0000</WeeklyAvailableHours>
  <CurrentAllocation>100</CurrentAllocation>
  <CurrentAvailableHours>0.0000</CurrentAvailableHours>
  <AvailableFrom nil="true"/>
  <AvailableFutureAllocation>0</AvailableFutureAllocation>
  <AvailableFutureHours>0.0000</AvailableFutureHours>
  <IsObserver>false</IsObserver>
  <IsContributor nil="true"/>
  <Locale>en</Locale>
  <Skills>ui</Skills>
  <ActiveDirectoryName>TP\falcon</ActiveDirectoryName>
  <Role ResourceType="Role" Id="8" Name="Head"/>
  <CustomFields>
    <Field Type="Text">
      <Name>Skill Set</Name>
      <Value nil="true"/>
    </Field>
  </CustomFields>
</User>

Troubleshooting

Use token in Excel integration

Q: I have a web query in an Excel file that pulls data from Targetprocess. How can I save my password into the query string — so I don't have to log in three times when I open up the file to update my data?

A: Please create Access Token value using personal details tab in Targetprocess:

And then append &access_token=token_value to your Excel API requests.

Find more details on Integration between Excel and Targetprocess.

Non Authorized error for System User

Q: I obtained a token for my System User. But when I try to use it, I receive a 401 Not Authorized response. How to proceed?

A: In order to establish any integrations where System User credentials are used you must set it's password. It seems you haven't set a password for your System User yet. Please set it in Targetprocess in Settings page → System Settings → General Settings → System User Credentials panel and save your changes.

Non Authorized error for on-site installations

Q: I am trying to use the Token value in my query string, but I am still getting a 401 Not Authorized response. I have an onsite installation. Any ideas?

A: That can probably happen because of Authentication settings in IIS for your local web site. Some of our customers enable Windows Authentication mode for their Targetprocess applications. In this mode Windows Active Directory records are used to authenticate users. In this case for REST client applications you should do the following:

• For the application root directory and /api/ inner directory please turn on Anonymous Authentication explicitly
• Use basic or token-based client authentication

Otherwise, you have to provide an NTLM authentication instead of basic one.