Skip to main content

TurnPoint API V2 - Access

Josh
  • Updated

Overview

TurnPoint's API Access Tokens (also known as Company Access Tokens or CAT) enable secure, automated integration with external systems, payroll providers, rostering software, and custom applications. This feature allows authorised administrators to generate secure access keys that third-party systems can use to interact with TurnPoint's API without requiring individual user credentials.

API V2 represents a significant upgrade from our original API and has a new access point and architecture that sits underneath. 

API V2 can be accessed via: api.turnpoint.co/v2/

What Are API Access Tokens?

API Access Tokens are company-level authentication credentials that provide controlled access to TurnPoint's API. Unlike user login credentials, these tokens:

  • Operate at the company level (not tied to individual user accounts)
  • Cannot be used to log in to the TurnPoint web interface
  • Have granular permission controls limiting which data and actions are accessible
  • Can be disabled instantly without affecting user accounts
  • Provide audit tracking for all API-initiated actions

Common Use Cases for API Access Tokens

  • Payroll Integration: Automatically export timesheet data to external payroll systems
  • Rostering Software: Sync appointment schedules with third-party rostering tools
  • Custom Reporting: Build automated reports that pull data from TurnPoint on scheduled intervals
  • Mobile Applications: Develop custom mobile apps that interact with TurnPoint data
  • Workflow Automation: Create automated processes that update records based on external triggers
  • Data Migration: Transfer data between TurnPoint and other business systems

Security and Authentication

How API Tokens Work

When an API access token is created, TurnPoint generates a unique, encrypted key that acts as the authentication credential for API requests. The system:

  1. Creates a special "bot" user account (system user) that cannot log in via the web interface
  2. Generates a one-way encrypted access token that is stored securely in the database
  3. Associates specific permissions (access tags) with the token
  4. Returns the token to the administrator only once during creation

Important Security Information

Critical: The API access token is displayed only once immediately after creation. TurnPoint uses one-way encryption, meaning the original token cannot be retrieved or viewed again after the creation dialogue is closed. If a token is lost, you must disable it and create a new one.

Store tokens securely in:

  • Password management systems
  • Secure environment variables on application servers
  • Encrypted configuration files

Never: Share tokens via email, store them in plain text files, commit them to code repositories, or include them in client-side code.

Prerequisites and Permissions

Who Can Manage API Access Tokens?

Only users with Unlock Permissions (typically company administrators) can access the API Access Tokens management area. If you cannot see the "API Access" option in your user menu, contact your system administrator to request appropriate permissions.

Company Token Limits

Each company is limited to 3 active API access tokens at any given time. This limit ensures controlled access and encourages proper token management. If you need to create a new token and have reached the limit, you must disable an existing token first.

API Fair Usage

By using the TurnPoint API, you agree to use the platform responsibly. This includes adhering to general usage principles, avoiding excessive or unnecessary data requests, and rate limiting your interactions to avoid placing undue load on the service.

TurnPoint reserves the right to modify the API at any time, with or without notice. This may include the introduction of pagination enforcement, rate limiting, or other access controls.

Accessing API Access Token Management

Step 1: Navigate to API Access

Click on your user menu (top-right corner of TurnPoint) and select API Access.

Step 2: View Existing Tokens

The API Access Tokens page displays all active and inactive tokens for your company. Each token card shows:

  • Token Name: Friendly identifier you assigned during creation
  • Status: Active or Inactive
  • Last Used: Date and time the token was last used for API authentication
  • Created By: User who generated the token
  • Expires At: Expiration date 
  • Permissions: Up to three access permissions displayed, with full list available via tooltip
  • Actions: Delete button for active tokens

Creating a New API Access Token

Step 1: Initiate Token Creation

Click the Add New Token button in the toolbar of the API Access Tokens page.

Step 2: Configure Token Settings

The token creation dialogue requires the following information:

Token Configuration Fields

Token Name (Required, max 25 characters)

Choose a descriptive name that identifies the token's purpose and the system using it. Examples:

  • "Xero Payroll Integration"
  • "Power BI Reporting"

Expiration Date 

Set an expiration date for the token. 

Access Permissions (Required - at least one)

Select which areas of TurnPoint the token can access. Available permissions include:

    • appointments:ViewAll
    • appointments:View
    • appointments:Update
    • appointments:Create
    • appointments:Cancel
    • appointments-activities:View
    • appointments-client:View
    • appointments-client:Send
    • appointments-timesheets:ViewAll
    • appointments-timesheets:View
    • appointments-timesheets:Update
    • appointments-transport:View
    • appointments-groupsessions:View
    • appointments-emailschedules:View
    • appointments-emailschedules:Send
    • appointments-groups:View
    • appointments-signature:View
    • settings:Update
    • settings-admin:Update
    • dashboard:View
    • dashboard-upcomingappointments:View
    • documents:View
    • reports:View
    • reports-dva:View
    • reports-dvanursing:View
    • reports-hacc:View
    • reports-soap:View
    • clients:View
    • clients-info:View
    • clients-packages:View
    • clients-referrers:View
    • clients-budgets:View
    • clients-budgets:Update
    • companies:View
    • companies:Update
    • company-clients:View
    • company-clientnotes:View
    • company-clientnotes:Update
    • company-clientholdperiods:View
    • company-forms:View
    • company-incidents:View
    • equipments:View
    • leaverequests:ViewAll
    • leaverequests:View
    • locations:View
    • medications:View
    • ndissupportitems:View
    • company-customforms:View
    • company-forms:View
    • company-incidents:View
    • company-sms:BulkSend
    • company-clientportal:View
    • payroll-payroll:View
    • payroll-tconnect-tconnect:View
    • paymenttypes:View
    • payrollcategories:View
    • suppliers:View
    • tasks-types:View
    • users:View
    • users:ViewAll
    • users:Update
    • users-departments:View
    • users-notifications:View
    • users-paygroups:View
    • users-paylevels:View
    • users-sms:Update
    • users-availability:View
    • weeklyplanner:View
    • maps-address:View
    • quickaccess:View
    • notifications-worker:View
    • notifications-admin:View
    • accounts-supplierinvoices:View
    • appointments:View
    • budgets:View
    • budgets:Update
    • company:View
    • company-forms:View
    • users-sms:BulkSend
    • appointments-casemanagement:View
    • appointments-casemanagement:Update
    • appointments-casemanagement:Settings
    • supportathome-services:Update
    • company-api:Update
    • appointments:BulkUpdate
    • users:Admin
    • supportathome-supplierinvoices:View
    • supportathome-supplierinvoices:Update
    • supportathome-supplierinvoices:Approve
    • supportathome-supplierinvoices:SeniorApprove
    • supportathome-supplierinvoices:Settings
    • supportathome-claims:View
    • supportathome-claims:Update
    • appointments:Download

 

Best Practices for Permission Selection

Principle of Least Privilege: Only grant the minimum permissions required for the integration to function. For example:

  • A payroll export only needs Timesheets (Read Only)
  • A rostering sync might need Appointments (Read/Write) and Staff (Read Only)
  • A custom reporting dashboard only needs Reports (Read Only)

Step 3: Generate and Save the Token

After clicking Create Token, TurnPoint displays the generated access token in a secure dialogue box.

CRITICAL: Save Your Token Immediately

This is your only opportunity to view and copy the token. TurnPoint uses one-way encryption and cannot display the token again after you close this dialogue.

  1. Click the Copy Token button to copy the token to your clipboard
  2. Immediately paste and save the token in a secure location
  3. Verify the token has been saved correctly before closing the dialogue
  4. Do NOT close the dialogue until you have confirmed the token is safely stored

If you accidentally close the dialogue without saving the token, you must disable the token and create a new one.

Using API Access Tokens

Authentication Format

To authenticate API requests using your access token, include it in the request headers:

HTTP Header Format

x-access-token: your_generated_token_here

x-access-key: your_generated_key_here

Example using Postman:
  1. Open your request in Postman
  2. Go to the Headers tab
  3. Add a new header with Key: x-access-token and x-access-key
  4. Set Value to your generated token
Managing Existing Tokens
Monitoring Token Usage
The Last Used field on each token card shows when the token was most recently used for authentication. Regular monitoring helps you:
  • Identify tokens that are no longer in use (candidates for disabling)
  • Verify that expected integrations are functioning
  • Detect unexpected token usage that may indicate security concerns
Disabling Tokens
When a token is no longer needed or may have been compromised, disable it immediately:
  1. Navigate to the API Access Tokens page
  2. Locate the token card you want to disable
  3. Click the Delete button on the token card
  4. Confirm the action in the prompt that appears
 
What Happens When a Token Is Disabled?
  • The token immediately stops authenticating API requests
  • Any systems using the token will receive authentication errors
  • The associated "bot" user account is marked as deleted (but preserved for audit purposes)
  • The token remains visible in the list marked as "Inactive"
  • Disabled tokens cannot be re-enabled - you must create a new token
Token Immutability
Important: API access tokens cannot be edited after creation. If you need to:
  • Change permissions → Create a new token with updated permissions, then disable the old token
  • Update the expiration date → Create a new token with the new expiration, then disable the old token
  • Rename the token → Create a new token with the new name, then disable the old token
This immutability ensures security and maintains clear audit trails of API access changes.
Troubleshooting
Authentication Errors (401 Unauthorised)
Possible Causes:
  • Token is expired or has been disabled
  • Token was entered incorrectly (check for extra spaces or missing characters)
  • Wrong header name (must be exactly access-token AND access-key)
  • Token was never properly saved during creation
Solutions:
  • Verify the token is still listed as "Active" in TurnPoint
  • Check the expiration date if one was set
  • Try copying and pasting the token again from your secure storage
  • If the token was lost, create a new token and update your integration configuration
Permission Denied Errors (403 Forbidden)
Cause: The token is authenticating successfully, but lacks the necessary permissions for the requested operation.
Solution: Review the permissions assigned to the token. Create a new token with additional permissions if needed, then update your integration to use the new token.
Cannot Create Token - Limit Reached
Cause: Your company has reached the maximum of 3 active API access tokens.
Solution: Review your existing tokens and disable any that are no longer in use. The "Last Used" date can help identify inactive tokens that are safe to disable.
Token Not Working After Creation
Possible Issues:
  • Not using the access-token header (note: no Authorization: prefix)
  • Attempting to use the token to log in to the web interface (tokens are API-only)
  • Making requests to the wrong API endpoint URL
 
Security Best Practices
Token Storage
  • Never store tokens in code repositories, even private ones
  • Use environment variables or secure configuration management systems
  • Encrypt configuration files containing tokens
  • Limit access to systems and staff who need the tokens
Token Rotation
  • Periodically create new tokens and disable old ones (recommended every 90-180 days)
  • Set expiration dates for tokens used by contractors or temporary integrations
  • Immediately disable tokens when staff with access leave the organisation
Monitoring and Auditing
  • Regularly review the "Last Used" dates for all active tokens
  • Investigate any tokens showing unexpected usage patterns
  • Maintain documentation of which tokens are used by which systems
  • Monitor API access logs for unusual activity (contact support for access to detailed logs)
What to Do If a Token Is Compromised
If you believe an API access token has been exposed or compromised:
  1. Disable the token immediately through the API Access Tokens interface
  2. Create a new token with fresh credentials
  3. Update all integrations to use the new token
  4. Contact TurnPoint support to review API access logs for suspicious activity
  5. Review your token storage and access practices to prevent future exposure
Frequently Asked Questions
Can I use the same token for multiple integrations?
While technically possible, it's not recommended. Create separate tokens for each integration to:
  • Maintain granular control over permissions
  • Track usage per integration via "Last Used" dates
  • Disable one integration without affecting others
  • Maintain clear audit trails
What happens to API calls in progress when I disable a token?
API calls in progress at the moment of disabling will complete, but any subsequent requests using the disabled token will immediately fail with authentication errors.
Can I increase the 3-token limit for my company?
The 3-token limit is a security measure applied to all companies. If you have a specific business case requiring additional tokens, contact support@turnpointcare.com.au to discuss your requirements.
How do API access tokens differ from user login credentials?
API access tokens:
  • Work only with API endpoints, not the web interface
  • Are company-level rather than user-specific
  • Have granular, limited permissions rather than full user access
  • Cannot be used for interactive sessions
  • Show as "bot" users in audit logs rather than named individuals
Will disabling a user account affect API tokens they created?
No. API tokens operate independently of individual user accounts. Tokens remain active even if the user who created them is disabled, though the "Created By" field will continue to show the original creator for audit purposes.
Getting Help
For assistance with API access tokens or integration questions:
  • Email: support@turnpointcare.com.au
  • Phone: 1300 110 127
     
When contacting support about API integration issues, please provide:
  • The name of the affected token
  • The API endpoint(s) you're attempting to access
  • Error messages received (excluding the actual token value)
  • Description of your integration's purpose
 
Important to Know
The TurnPoint API is not a feature of the TurnPoint Assist product. It is an additional benefit provided to enable providers to extend and enhance their use of the software.
Use of the API is subject to TurnPoint's Terms and Conditions. TurnPoint reserves the right to suspend or terminate API access for any provider found to be misusing the platform.


          

          
            

              
            

          
        

      


      

      

        
          

        
        
          
  

    
      
Related articles

    
    
  



        
      

      
        

          

            

              

                Comments
              

              
0 comments

              
            


            
    
              
            


            

            

            
Please sign in to leave a comment.