Authenticating into the web API requires a separate login session from the normal TeamDynamix application.
Documentation on the authentication methods can be found here:
https://yourTeamDynamixDomain/TDWebApi/Home/section/Auth
(replace yourTeamDynamixDomain with your organizational URL domain, such as myschool.teamdynamix.com)
Authentication Methods
The TeamDynamix API supports the following authentication methods. Each option has different times where it is appropriate.
- Authenticating as a specific User or Service Account with a username and password
- Authenticating as an Admin Service Account with a BEID and Web Services Key
As noted in the No Single Sign On (SSO) Support section below, the API does not support SSO logins. Please refer to the below section for more details.
Username and Password
You can access the TeamDynamix API using a username and password when you want to act as a specific User or a specific Service Account. If you use the username and password of a User, the API call will check that user's permission and will act as if that user had taken the actions specified in the API request. Service Accounts are similar to Users, as they have specific permission and application access. If you use a Service Account's username and password to access the API it will use the Service Account's permissions.
Whether you're using a User or a Service Account, authentication via username and password uses the following API request:
POST /api/auth/login HTTP/1.1
Content-Type: text/json; charset=utf-8
{username: "user", password: "password"}
Web Services Key
You can also access the API using the BEID (tenant ID) and a Web Services Key from an Admin Service Account. Admin Service Accounts are required for certain API endpoints (generally ones that don't have an equivalent way to do the action as a user). If you use an Admin Service Account for an endpoint that doesn't require it, the API will act as if the user has full permissions for the endpoint.
Authentication using this method uses the following request:
POST /api/auth/loginadmin HTTP/1.1
Content-Type: text/json; charset=utf-8
{"BEID":"df0b5273-d7d4-44a3-9dbb-73a57c2904a9","WebServicesKey":"2313ed32-7b4c-4c5b-8974-126a638d0de1"}
Actions taken using these credentials will be displayed in the system using the name of the Admin Service Account.
Authentication Response
A successful call will return a JSON Web Token (JWT) in the body of its response, like so:
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJURCIsImF1ZCI6Imh0dHBzOi8vd3d3LnRlYW1keW5hbWl4LmNvbS8iLCJuYmYiOjE0MDA3MDUwNzQsImV4cCI6MTQwMDc5MTQ3NCwidW5pcXVlX25hbWUiOiJUZXN0VGVhbUR5bmFtaXhVc2VyIn0.tiRPGaawhPSy__B_xoyiQ7-mD2GUaBVk10BOsO1eoE8
This token must be included as an Authorization header (of type "Bearer") in any subsequent requests, like in the following request:
GET /api/tickets/123456 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1[truncated]
Many HTTP client libraries allow you to specify a default set of HTTP headers to include with each request, and so a successful authentication response could simply update the default value of the Authorization header sent in any subsequent requests.
No Single Sign On (SSO) Support
The API has no support for Single Sign On (SSO) authentication for any automated scripting processes. You must use a non-SSO TeamDynamix User-typed account, service account or admin service account to authenticate.
The POST /TDWebApi/api/auth/loginsso endpoint is only really meant for internal TeamDynamix usage in TeamDynamix client-side javascript code. It is not a method for authenticating into the API from external scripting solutions.