Authentication & Scopes

Authentication

API keys are sent in the Authorization header using the Bearer scheme:

Authorization: Bearer gb_live_your_api_key_here

Example cURL Request

curl -X GET "https://airtasystems.com/api/v2/compliance" \
  -H "Authorization: Bearer gb_live_your_api_key_here"

Example JavaScript (fetch)

const response = await fetch('https://airtasystems.com/api/v2/compliance', {
  headers: {
    'Authorization': 'Bearer gb_live_your_api_key_here'
  }
});

Example Python (requests)

import requests

headers = {
    'Authorization': 'Bearer gb_live_your_api_key_here'
}

response = requests.get('https://airtasystems.com/api/v2/compliance', headers=headers)

Available Scopes

Scopes control what data your API key can access. Each endpoint requires specific scopes.

Scope	Description	Required For
read:programs	Read program information	Program details, program listings
read:submissions	Read submission/report data	Submissions, messages
read:users	Read user information	User profiles, user data
read:teams	Read team information	Team details, team members, team performance metrics, internal/external teams
read:reports	Read compliance reports	Compliance documents, FRIA assessments, incident reports

Scope Requirements by Endpoint

Compliance Documents

• Endpoint: GET /api/v2/compliance
• Required Scope: read:reports

Submissions

• Endpoint: GET /api/v2/submissions
• Required Scope: read:submissions

Incident Reports

• Endpoint: GET /api/v2/incidents/reports
• Required Scope: read:reports

FRIA Assessments

• Endpoint: GET /api/v2/fria/assessments
• Required Scope: read:reports

Messages

• Endpoint: GET /api/v2/messages
• Required Scope: read:submissions

Teams

• Endpoint: GET /api/v2/teams
• Required Scope: read:teams
• Description: Get your company's internal teams

Team Details

• Endpoint: GET /api/v2/teams/:teamId
• Required Scope: read:teams
• Description: Get detailed information about a specific team

Team Members

• Endpoint: GET /api/v2/teams/:teamId/members
• Required Scope: read:teams
• Description: Get members of a specific team

Insufficient Scopes Error

If your API key doesn't have the required scope, you'll receive:

{
  "success": false,
  "error": "insufficient_scopes",
  "message": "API key lacks required permissions for this endpoint"
}

HTTP Status: 403 Forbidden

To fix this, update your API key in API Key Management to include the required scope.

Best Practices

• Minimal permissions - Only grant scopes you actually need
• Separate keys - Use different keys for different integrations
• Regular review - Periodically review and remove unused scopes
• Documentation - Document which scopes each integration requires