Authentication

Total Access uses two authentication methods depending on your integration type.

API Keys

API keys are long-lived tokens ideal for server-to-server integrations. They can optionally be set to expire on a specific date; if no expiry is set, they remain valid until revoked.

Generating an API key

Log in to your Total Access account
Navigate to Total Integration → API Keys
Click Create API Key
Name your key (e.g., "Production Sync")
Select the scopes/permissions
Copy the key immediately — it's shown only once

Using an API key

Pass your API key in the X-API-Key header:

curl -X GET https://totalaccess.co.za/api/v1/me \
  -H "X-API-Key: ta_sk_your_api_key_here" \
  -H "Content-Type: application/json"

For the Public Data API and MCP Bridge, the X-API-Key header is the only accepted authentication method.

API keys grant the same permissions as the user who created them. Use scoped keys with minimal permissions for production integrations.

Revoking a key

To revoke an API key:

Go to Total Integration → API Keys
Find the key and click Revoke
All requests using that key will immediately return 401 Unauthorized

JWT Tokens

JWT tokens are used for user-facing applications where users log in with their Total Access credentials.

Token lifecycle

Token	TTL	Purpose
Access token	15 minutes	Authenticate API requests
Refresh token	7 days	Obtain new access tokens

curl -X POST https://totalaccess.co.za/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your_password"
  }'

Response:

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 900
  }
}

Refreshing tokens

curl -X POST https://totalaccess.co.za/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "your_refresh_token"
  }'

Refresh tokens are single-use. Each refresh returns a new refresh token. Reusing an old refresh token will invalidate the entire token chain (reuse detection).

Scopes

API keys are scoped to specific permissions. Scopes are grouped by category:

Users & Employees

Scope	Description
`users:read`	Read user information
`employees:read`	Read employee records and details
`employees:write`	Create and update employee records

Operations

Scope	Description
`work_items:read`	Read work items (jobs, tasks, projects)
`work_items:write`	Create and update work items
`work_items:delete`	Delete work items
`appointments:write`	Create and update appointments
`comments:write`	Add comments to work items
`recurring:write`	Create and manage recurring job schedules

Threads & Messaging

Scope	Description
`threads:read`	Read job threads and messages
`threads:write`	Create and manage threads
`threads:send_message`	Send messages to threads

Time & Attendance

Scope	Description
`attendance:read`	Read clock in/out records and attendance logs
`attendance:write`	Create clock in/out records (proxy clocking)
`shifts:read`	Read shift templates and assignments
`shifts:write`	Create and update shift templates and assignments
`roster:read`	Read shift roster and schedules
`roster:write`	Create and update shift roster entries
`locations:read`	Read locations and geofence identifiers
`locations:write`	Create and update locations and geofences
`timesheets:read`	Read timesheet records
`timesheets:write`	Create and update timesheets
`timesheets:approve`	Approve or reject timesheets
`overtime:read`	Read overtime records
`overtime:write`	Create and approve overtime requests

Finance

Scope	Description
`invoices:read`	Read invoices
`invoices:write`	Create and update invoices
`quotes:read`	Read quotes
`quotes:write`	Create and update quotes
`bills:read`	Read bills (supplier invoices)
`bills:write`	Create and update bills
`payments:read`	Read payment records
`payments:write`	Create and update payments
`chart_of_accounts:read`	Read chart of accounts
`chart_of_accounts:write`	Create and update accounts
`journal_entries:read`	Read journal entries
`journal_entries:write`	Create and post journal entries

Contacts & Inventory

Scope	Description
`contacts:read`	Read customer and supplier contacts
`contacts:write`	Create and update contacts
`inventory:read`	Read stock levels and movements
`inventory:write`	Update stock and create movements
`products:read`	Read products and services
`products:write`	Create and update products

Fleet

Scope	Description
`vehicles:read`	Read vehicle information and fleet data
`vehicles:write`	Create and update vehicle records
`tracking:read`	Read GPS tracking and location data
`tracking:write`	Update tracking settings and geofences

Forms

Scope	Description
`forms:read`	Read form definitions, stats, analytics, and submissions
`forms:write`	Create and update form definitions and sharing settings
`forms:submit`	Create form submissions via authenticated APIs
`forms:submissions:read`	Read and export form submissions

WhatsApp & Support

Scope	Description
`whatsapp:connect`	Connect and manage WhatsApp instances
`whatsapp:send`	Send WhatsApp messages
`whatsapp:receive`	Receive WhatsApp messages and webhooks
`whatsapp:status`	Check WhatsApp connection status
`support:read`	Read support tickets and conversations
`support:write`	Create and update support tickets

System

Scope	Description
`webhooks:manage`	Manage webhooks
`webhooks:receive`	Receive inbound webhook data
`settings:read`	Read client settings
`settings:write`	Update client settings
`reports:read`	Access reports and analytics
`reports:export`	Export reports to PDF/Excel

API key permissions are stored as { "scopes": ["scope1", "scope2", ...] }. Scope validation supports wildcard matching (e.g. finance:* matches all finance scopes).

API key environments

API keys have an environment setting:

Environment	Key Prefix	Playground	Full Key Visible
`testing`	`ta_sk_`	Yes — usable in test playground	Yes (returned on list)
`production`	`ta_sk_`	No — protected from test use	No (masked, requires reveal)

IP allowlisting

API keys can be restricted to specific IP addresses. When set, requests from other IPs return 403 Forbidden:

{
  "allowed_ips": ["192.168.1.100", "10.0.0.0/24", "41.123.45.67"]
}

Supports both individual IPs and CIDR notation. Leave empty to allow all IPs.

API key reveal

Production API keys are masked in list views (ta_sk_abc...wxyz). To reveal the full key:

curl -X POST https://totalaccess.co.za/api/v1/integrations/api-keys/42/reveal \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "password": "your_account_password" }'

The reveal requires the user's account password and is logged to an audit trail with IP address and user agent.

API key audit trail

All sensitive API key actions are logged:

Reveal — When a production key is revealed (IP, user agent, timestamp)
Usage — last_used_at updated on each authenticated request
Usage stats — Total requests, 24h count, 7d count per key

Error responses

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key"
  }
}

Status	Code	Meaning
401	`UNAUTHORIZED`	Missing or invalid credentials
401	`TOKEN_EXPIRED`	JWT access token has expired
403	`FORBIDDEN`	Valid auth but insufficient permissions
429	`RATE_LIMITED`	Too many requests

Authentication

On this page