Support resources Try now

Authentication

All API requests must contain some mechanism for identifying the user and ensuring they are authorized to make the request. The TeamPulse API uses the OAuth Wrap protocol for this purpose, and as such all requests have to provide an Access Token. Access tokens are issued from the Security Token Service (STS) after a user provides valid credentials. The TeamPulse log-in page uses cookie-based authentication, so if you are using TeamPulse in a browser the server will recognize the cookies and will log you in. In that case an Access Token is not required.

Sample Application

To see a simple authentication demo in .NET and javascript go to Example Application. If you like to know more details about the authentication process you can continue reading.

Getting an Access Token

When you try to access the API, if you don’t provide an Access Token, the server will return an Unauthorized response with the following headers:

Response
HTTP/1.1 401 Unauthorized
WWW-Authenticate: WRAP location="http://[TeamPulse]/Authenticate/WRAPv0.9", client_id=uri:TeamPulse

The WRAP location and client_id are required parameters to get the Access Token.

An Access Token can be acquired in 3 ways:

  1. With username and password.
  2. With login into a registered Identity Provider (IP). Also known as RichClientAppProfile.
  3. With an existing Refresh Token.

The preferred way to login is with RichClientAppProfile because it allows you to login with all registered providers. Username and password will work only with the local identity provider.

Note: The responses are url encoded so when you get them you need to decode the body.

Sample Request with Access Token

You should add header "Authorization" with value "WRAP access_token={UrlEncoded (Access Token)} to every request. You have to encode the Access Token.

Request
GET http://[teampulse]/api/projects HTTP/1.1
Authorization: WRAP 
access_token=http%253a%252f%252fschemas.xmlsoap.org%252fws%252f2005%252f05%252fidentity%252fclaims%252fname%3dbooboo%26http%253a%252f%252fschemas.xmlsoap.org%252fws%252f2005%252f05%252fidentity%252fclaims%252femailaddress%3dbooboothebear%2540telerik.com%26http%253a%252f%252fschemas.xmlsoap.org%252fws%252f2005%252f05%252fidentity%252fclaims%252fprivatepersonalidentifier%3d69a49a5b-fff7-4b48-bc68-e4ce5ffa27c9%26http%253a%252f%252fschemas.telerik.com%252f2012%252f03%252fidentity%252fclaims%252fdomain%3dSqlProvider%26TokenId%3d049b6dbf-5896-4676-96e4-24c4aa14600c%26Issuer%3dhttp%253a%252f%252flocalhost%252fTeamPulse%252fAuthenticate%252fWRAPv0.9%26Audience%3dhttp%253a%252f%252flocalhost%252fTeamPulse%26ExpiresOn%3d1345136297%26HMACSHA256%3d8CwGbh3H2INvRd7rf87rhFXIPx3GYvjOmbXApOZPkRY%253d

Login

Login with username and password

Login with username and password by sending the following request to server to get the Access Token.

Request
POST http://[TeamPulse]/Authenticate/WRAPv0.9 HTTP/1.1
Content-type: application/x-www-form-urlencoded

wrap_client_id = uri:TeamPulse
wrap_username = user
wrap_password = pass
Response
HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded; charset=utf-8

wrap_access_token=http%253a%252f%252fschemas.xmlsoap.org%252fws%252f2005%252f05%252fidentity%252fclaims%252fname%3dbooboo%26http%253a%252f%252fschemas.xmlsoap.org%252fws%252f2005%252f05%252fidentity%252fclaims%252femailaddress%3dbooboothebear%2540telerik.com%26http%253a%252f%252fschemas.xmlsoap.org%252fws%252f2005%252f05%252fidentity%252fclaims%252fprivatepersonalidentifier%3d69a49a5b-fff7-4b48-bc68-e4ce5ffa27c9%26http%253a%252f%252fschemas.telerik.com%252f2012%252f03%252fidentity%252fclaims%252fdomain%3dSqlProvider%26TokenId%3dad3ec227-b977-4eb0-ad72-667ab01f3e8e%26Issuer%3dhttp%253a%252f%252flocalhost%252fTeamPulse%252fAuthenticate%252fWRAPv0.9%26Audience%3dhttp%253a%252f%252flocalhost%252fTeamPulse%26ExpiresOn%3d1345126638%26HMACSHA256%3d0LDR4w%252bNV3sOOnmR0JLagtbqpdhMFIbV1JQVNjvbHAE%253d&wrap_refresh_token=42sEcK3eXebkdu9fkg7Da6i6%2b3bD9qSCfdFKqR%2fk1wEkGyLUf%2b8000X%2fsVT2EE3wLiTohXxS31BBdK833IgNqRknk%2bVUy%2favX0xXMnYCTfBTL9DAPNoeEREBLhY0zix22a54GBOV9vag2bHecdn7WpW3Rw9M3tV%2fb5ofWhqrQq4%2bvdLD8DXgI6mCK4Kh8oBiEcw0FTlDoD2bqUZ4jUYlDDPNMCYFhb7wHn%2bL5QSTlGsHafyG0zcNEmoP94d3dR7ltAAAAA%3d%3d&wrap_access_token_expires_in=3600

In the body of the Response you will find the Access Token and Refresh Token.

Login with the RichClientAppProfile

When you want to use all available providers for authentication the suggested way is to directly open the TeamPulse login page.

  1. You need to open a browser from your app and navigate to the login page http://[teampulse]/Authentication/RichAppLogin.
  2. On successful login you will receive a Verification Code.
  3. Send the verification token to the server to get the Access Token.
Request
POST http://[TeamPulse]/Authenticate/WRAPv0.9 HTTP/1.1
Content-type: application/x-www-form-urlencoded

wrap_client_id=uri:TeamPulse&wrap_verification_code=730FE9F7313AB763224E24ED3A18074D9328185F01026931612526595075F2C0
Response
HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded; charset=utf-8

wrap_access_token=http%253a%252f%252fschemas.xmlsoap.org%252fws%252f2005%252f05%252fidentity%252fclaims%252fname%3dbooboo%26http%253a%252f%252fschemas.xmlsoap.org%252fws%252f2005%252f05%252fidentity%252fclaims%252femailaddress%3dbooboothebear%2540telerik.com%26http%253a%252f%252fschemas.xmlsoap.org%252fws%252f2005%252f05%252fidentity%252fclaims%252fprivatepersonalidentifier%3d69a49a5b-fff7-4b48-bc68-e4ce5ffa27c9%26http%253a%252f%252fschemas.telerik.com%252f2012%252f03%252fidentity%252fclaims%252fdomain%3dSqlProvider%26TokenId%3d049b6dbf-5896-4676-96e4-24c4aa14600c%26Issuer%3dhttp%253a%252f%252flocalhost%252fTeamPulse%252fAuthenticate%252fWRAPv0.9%26Audience%3dhttp%253a%252f%252flocalhost%252fTeamPulse%26ExpiresOn%3d1345136297%26HMACSHA256%3d8CwGbh3H2INvRd7rf87rhFXIPx3GYvjOmbXApOZPkRY%253d&wrap_refresh_token=%2bGMSVa7X1RO3pxP0010x9n7iCfpits0Qs5ztj7uAouEtuPnKSyyvTr5tiG4dTNDQUgrsRtedFYpt4i68iU0RmkVmchC6zeAtwRZrseSfhv6xMTd0Rcblkc1lskiwSrObCAz44S8%2f00tFDU0sRPDHJ8Nm5AXvOZ%2b7yDngf3J%2b0LTFbYIlDte6u7OGNBvPpZN2mp1bEBxTMMszXsjcW7fOzKvIrdf7RTRAdV79OkODcUR4zHufCB%2fIPQTcEqdArN5vtAAAAA%3d%3d&wrap_access_token_expires_in=3600

Login with an existing Refresh Token

On successful login in addition to the access token you will receive a refresh token. You can use that refresh token to acquire a new access token.

Request

POST http://[TeamPulse]/Authenticate/WRAPv0.9 HTTP/1.1
Content-type: application/x-www-form-urlencoded

wrap_client_id=uri:TeamPulse&wrap_refresh_token=42sEcK3eXebkdu9fkg7Da6i6%2b3bD9qSCfdFKqR%2fk1wEkGyLUf%2b8000X%2fsVT2EE3wLiTohXxS31BBdK833IgNqRknk%2bVUy%2favX0xXMnYCTfBTL9DAPNoeEREBLhY0zix22a54GBOV9vag2bHecdn7WpW3Rw9M3tV%2fb5ofWhqrQq4%2bvdLD8DXgI6mCK4Kh8oBiEcw0FTlDoD2bqUZ4jUYlDDPNMCYFhb7wHn%2bL5QSTlGsHafyG0zcNEmoP94d3dR7ltAAAAA%3d%3d

Response

HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded; charset=utf-8

wrap_access_token=http%253a%252f%252fschemas.xmlsoap.org%252fws%252f2005%252f05%252fidentity%252fclaims%252fname%3dbooboo%26http%253a%252f%252fschemas.xmlsoap.org%252fws%252f2005%252f05%252fidentity%252fclaims%252femailaddress%3dbooboothebear%2540telerik.com%26http%253a%252f%252fschemas.xmlsoap.org%252fws%252f2005%252f05%252fidentity%252fclaims%252fprivatepersonalidentifier%3d69a49a5b-fff7-4b48-bc68-e4ce5ffa27c9%26http%253a%252f%252fschemas.telerik.com%252f2012%252f03%252fidentity%252fclaims%252fdomain%3dSqlProvider%26TokenId%3d3b082c3f-7992-4ca9-87fa-2627d0b23b32%26Issuer%3dhttp%253a%252f%252flocalhost%252fTeamPulse%252fAuthenticate%252fWRAPv0.9%26Audience%3dhttp%253a%252f%252flocalhost%252fTeamPulse%26ExpiresOn%3d1345131752%26HMACSHA256%3d9riANH455cTqW8kiCcf2ZTBer%252fepHL9oHYD0i61Wztg%253d&wrap_refresh_token=ftNGaWKt4CmoaBOnCIpuiyGwabrXfJqn2otDM6JIKxWkyrk3aqzIYHox3bmDX4Utc0jmj2cRE4Zeg4tjw%2fHUmELdBlntp51%2brT1FmocCyu8r%2f%2bGcE5y82nBNaGtJjHAd2IXH4SFP6VSp018zBRqB%2fTbFnJBz%2f8iyC7tn8tdoMY6c9ESXgnrQvftUhPM6yNkVKtciWVvxErAghhLXFePAB2gJi4tyB797zE1M1XRHFcCliV2R90S8tZ8XfxyiKcXqtAAAAA%3d%3d&wrap_access_token_expires_in=3600