Skip to main content

API Keys (V2)

Updated

API Keys (V2) provide secure access to the PeopleTray APIs, allowing external systems to retrieve and interact with data. API Keys can be configured with optional IP restrictions, monitored through detailed usage logs, and managed directly within TeamTray settings. A maximum of 5 active API keys for your account can be maintained at any one time.

Important: Revoking an API key is permanent and cannot be undone. If a key is revoked, a new key must be generated.

Location

TeamTray > Settings > Data > APIs > API Keys

All PeopleTray's API Endpoints can be found here: https://api-peopletray.azurewebsites.net/swagger/ui/index#/

Creating an API Key

When creating a new API key, you will be prompted to:

  • Enter a name for the key
  • Optionally assign an IP address restriction

IP Restriction:

  • If applied, the IP address must be a public IP address
  • Requests from any other IP address will be blocked with an “Unauthorised” error
  • IP restrictions can be added or removed after the key is created

Expiration:

  • API keys are set to expire one year from the date of creation by default

Security Considerations

Once an API key is created, it will be displayed only once.

  • The key must be saved securely immediately
  • Anyone with access to the key can access your PeopleTray data via the API
  • It is recommended to store keys in a secure credential manager or vault

Revoking an API Key

To deactivate an API key:

  1. Locate the key in the API Keys list
  2. Click Revoke
  3. Confirm the action in the prompt

This action is permanent and cannot be reversed.

How to Use an API (V2)

API (V2) endpoints are available via Swagger UI and currently include:

  • PowerBIV2
  • ReportingV2

Base URL:

https://api.peopletray.com

Example Request:

To retrieve data from the PowerBI people endpoint:

https://api.peopletray.com/api/v2/powerbi/people

Parameters:

  • Available parameters (e.g. date ranges, workgroups) can be viewed and configured in Swagger UI
  • Expand the relevant endpoint to see all supported filters

 

Using the new API Key

Once you've created the new API key, you can add the header X-API-Key. The 'Value' for this header, you can copy/paste the API V2 key into. This is different to the old API authorization. Screenshot below shows the postman setup for API V2 - using the V2 Reporting checklists API endpoint:

 

API Usage Logs

API activity can be monitored via: TeamTray>Settings>Data>APIs>API Key Usage Log

Available Information

The usage log provides a detailed record of all API requests, including:

  • IP address used
  • Date and time of the request
  • API key name
  • HTTP method
  • HTTP response status

Troubleshooting

  • Failed requests include a Failure Reason
  • Additional details can be viewed by hovering over the Message field
  • This information can be used to diagnose and resolve issues

 

Powered by Zendesk