What is the TeamForm Public API?

TeamForm offers a public API which customers and integrators can be use to access TeamForm data.

Documents are published as an OpenAPI (swagger) specification at http://app.teamform.co/api-docs

For customers using a branded URL please access /api-docs to your customer URL or access via the Support icon within the app.

How can I get an API secret / access?

Please raise a support request via https://www.teamform.co/help
Request an API secret, include the tenant and workspace (you will need to be a TeamForm administrator, or have obtained their permission to obtain api access)
- Upon successful completion of your request, you will receive from TeamForm a client_id, and a client_secret.
- Both pieces of information should be treated like a password - keep them secret, and only store them securely.

Why do people use the API?

The most common use case for the API is to integrate with downstream systems that need team and membership data and as a mechanism to export data for the purposes of reporting and analytics in a customer data warehouse / lake.
We are continuing to evolve the API over time as we discuss new use cases with customers.

Where can I find my tenant and workspace IDs?

This information is visible by doing the following steps
On the left hand menu (towards the bottom) click on the Question mark icon ？
From there you will be presented with API doc guidance (bottom section) and the associated tenant and workspace IDs respectively. These are needed for you to create your API queries.

How do I get a bearer token and how does it work (e.g. expiry etc.)

What is bearer authentication / breaker token https://swagger.io/docs/specification/authentication/bearer-authentication/
How do I get a bearer token once I have my API secret? Make the following call (token expires each 24 hours)

curl --request POST \
  --url https://orchestrated-integration.au.auth0.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{"client_id":"<clientID>","client_secret":"<clientSecret>","audience":"https://api.teamform.co/<tenant id>/api","grant_type":"client_credentials"}'

Making your first query

Calls are structured https://api.teamform.co/<tenant id>/api/<api call>
For example, Get Teams is https://api.teamform.co/<tenant id>/api/getTeams

Considerations for using the API

Data is real time (vs access via TeamForm reporting which has a ~1hr lag)
Can be integrated into Enterprise applications or reporting suites such as PowerBI and Tableau
Excessive calls can impact performance of a customer TeamForm instance

What does a typical API call flow look like, once I have my key and ID?

to begin, use the secret key and Client ID to make a request for a TeamForm API access token.
- this access token will automatically expire after 24 hours, dee above for an example.
you can now start making requests! On each request, you must include your access token, gained above. For example, to make a cURL request to the getTeams endpoint:
- curl --request GET \ --url https://orchestrated-integration.au.auth0.com/<tenant id>/api/getTeams --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <access token>' --data '<your request payload>'
  Note: you’ll also need to add in your <tenant id> to this example, in the --url section.

Troubleshooting

this stage requires access to CloudWatch logs in AWS. please work with an engineer

AWS console account
Assume role to TeamFormEngineer - may work with the analyst role TBD
Picking the correct log group
- for the public API, the format is tf-be-prod-<tenantId>-publicApiLambda<otherCharacters>, eg /aws/lambda/tf-be-prod-zgqr-publicApiLambdaD742A363-VBTQL6Z1Utwa

see what’s happened - using AWS CloudWatch Logs

a filter. this watches for any activity against the CLIENT_ID. this lets us see what each specific set of credentials is doing

fields @timestamp, @message, @event, @response
| filter operatorId = '<CLIENT_ID>'
| display @timestamp, @logStream, operatorId, workspaceId, transactionId, level, event.requestContext.path, msg, response.statusCode, response.body
| sort @timestamp desc

can look for errors in the function

can look at where we returned an error to the client

looking for errors/warnings in the function and 4xx/5xx responses to the client

What this looks like in CloudWatch - looking at a specific CLIENTID

note the saved queries on the right (public-api-queries…)
note the timeframe at the top (1hr, also look at 1d, 1w)

example - all activity against a given CLIENT_ID

example: function errors & warnings, or anything that we sent a 4xx/5xx response code back