Authentication

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

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>xxx@xxx.com</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 Access Tokens tab:

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 > Authentication and Security > System User panel** and save your changes.