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:
- Locate the key in the API Keys list
- Click Revoke
- 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