OAuth2 Developer Portal

The Total Access OAuth2 provider allows third-party developers to build integrations that access Total Access data on behalf of users. This guide covers creating apps, the marketplace, and the developer onboarding flow.

Overview

The OAuth2 provider supports two flows:

Authorization Code + PKCE — for client-side apps, mobile apps, and SPAs
Client Credentials — for server-to-server integrations

See the OAuth2 API Reference for endpoint details and scope definitions.

Create a developer profile

Before creating apps, set up your developer profile:

curl -X GET https://developer.totalaccess.co.za/api/v1/oauth/developer-profile \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Update your display name:

curl -X PATCH https://developer.totalaccess.co.za/api/v1/oauth/developer-profile \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "display_name": "Acme Integrations" }'

Create an OAuth2 app

Register your app

curl -X POST https://developer.totalaccess.co.za/api/v1/oauth/apps \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "app_name": "Acme Invoice Sync",
    "description": "Syncs invoices from Total Access to your accounting system",
    "redirect_uris": ["https://app.acme.com/oauth/callback"],
    "scopes": ["work_items:read", "finance:read"],
    "auth_flows": ["authorization_code"],
    "is_public": true
  }'

Save your client secret

The response includes a client_secret that is only shown once. Store it securely.

Use the authorization flow

Redirect users to:

https://developer.totalaccess.co.za/api/v1/oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://app.acme.com/oauth/callback&
  scope=work_items:read finance:read&
  code_challenge=GENERATED_CHALLENGE&
  code_challenge_method=S256&
  state=RANDOM_STATE

Exchange the code for tokens

curl -X POST https://developer.totalaccess.co.za/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code": "AUTHORIZATION_CODE",
    "code_verifier": "YOUR_CODE_VERIFIER",
    "redirect_uri": "https://app.acme.com/oauth/callback"
  }'

Manage your apps

List all your apps:

curl -X GET https://developer.totalaccess.co.za/api/v1/oauth/apps \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Update an app:

curl -X PATCH https://developer.totalaccess.co.za/api/v1/oauth/apps/APP_UUID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Updated description" }'

Regenerate client secret (invalidates the old one immediately):

curl -X POST https://developer.totalaccess.co.za/api/v1/oauth/apps/APP_UUID/regenerate-secret \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Marketplace

Public apps are listed in the marketplace once approved by an admin.

Browse the marketplace:

curl -X GET https://developer.totalaccess.co.za/api/v1/oauth/marketplace \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Filter by category:

curl -X GET "https://developer.totalaccess.co.za/api/v1/oauth/marketplace?category=finance" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Onboarding

The developer onboarding flow tracks your progress through key milestones:

curl -X GET https://developer.totalaccess.co.za/api/v1/oauth/onboarding \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Record a milestone:

curl -X POST https://developer.totalaccess.co.za/api/v1/oauth/onboarding \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "milestone": "first_app_created" }'

Completing onboarding milestones unlocks additional features like higher rate limits and marketplace listing eligibility.

OAuth2 Developer Portal

On this page