Skip to main content
Authorisation management allows you to track and verify user authorisation for data sharing. Teal provides default authorisation terms, or you can create custom terms tailored to your business requirements.

​
Authorisation Terms

Authorisation terms define the legal text that users agree to when granting access to their data.

​
System Terms vs Custom Terms

TypeDescription
System TermsDefault terms provided by Teal, available to all clients. Identified by is_system_term: true.
Custom TermsTerms created by your organization for specific use cases. Identified by is_system_term: false.

​
Categories

Each term belongs to a category that defines the type of authorisation:
  • one_time - Single authorisation for a specific action (e.g., one-time income verification)
  • recurring - Ongoing authorisation for continuous data access (e.g., recurring payroll checks)

​
Retrieving Available Terms

curl --request GET \
  --url 'https://api.sandbox.goteal.co/authorisations/terms' \
  --header 'X-API-KEY: <api-key>'
Filter by type using query parameters: 
# Get only system terms
GET /authorisations/terms?is_system_term=true

# Get only recurring terms
GET /authorisations/terms?authorisation_category=recurring

# Combine filters
GET /authorisations/terms?is_system_term=true&authorisation_category=recurring

​
Creating Custom Terms

If system terms don’t meet your requirements, create custom terms: 
curl --request POST \
  --url https://api.sandbox.goteal.co/authorisations/terms \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '{
    "name": "Custom Data Sharing Agreement",
    "authorisation_text": "I authorize Example Corp to access my payroll data for income verification purposes.",
    "authorisation_category": "recurring"
  }'
The authorisation_version is automatically assigned and incremented for each new term you create.

​
Managing Active Terms

By default, creating a new term keeps any existing active terms in the same category active. Use the optional deactivate_previous flag to control this behavior: 
curl --request POST \
  --url https://api.sandbox.goteal.co/authorisations/terms \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '{
    "name": "Updated Data Sharing Agreement",
    "authorisation_text": "Updated authorisation text...",
    "authorisation_category": "recurring",
    "deactivate_previous": true
  }'
deactivate_previousBehavior
false (default)New term is created. Existing active terms remain active.
trueNew term is created. Any existing active term for the same category is set to is_active: false.
When you deactivate previous terms, users who accepted the old term will need to re-authorise to the new term (see Re-authorisation Flow).

​
Getting the Latest Term for a User

To get the appropriate authorisation term for a user based on their recurring check configuration: 
curl --request GET \
  --url 'https://api.sandbox.goteal.co/authorisations/terms/latest?user_id=95a0e70b-fe02-4f47-aef9-2efff279df71' \
  --header 'X-API-KEY: <api-key>'
This endpoint automatically resolves to either the one_time or recurring category based on the user’s configuration.

​
Recording Authorisation

When a user accepts authorisation terms, record their acceptance: 
curl --request POST \
  --url https://api.sandbox.goteal.co/authorisations \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '{
    "user_id": "95a0e70b-fe02-4f47-aef9-2efff279df71",
    "term_id": "550e8400-e29b-41d4-a716-446655440000",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
  }'
term_id is optional. If it is absent in the request, then the latest active term is searched against the user’s current setting. For example, if they have reucrring checks enabled then it will resolve to the latest active term matching this category. If the term_id is supplied you can choose which term the user is accepting, provided it is active. No category matching is done currently for an explcitly provided term.

​
Optional Fields

FieldBehavior
term_idOptional. If not provided, auto-resolves to the latest active term based on user’s recurring check configuration.
ip_addressOptional. If not provided, captured from request headers. Use when recording authorisation via server-to-server calls.

​
Authorisation Record

Each acceptance creates an immutable record containing:
  • id - Unique authorisation record identifier
  • user_id - The user who gave authorisation
  • term_id - The specific term version accepted
  • ip_address - Captured from request headers or provided in request
  • user_agent - Browser or application identifier
  • accepted_at - Server timestamp of acceptance
  • status - active or revoked

​
Validating Authorisation

Before performing actions that require authorisation, verify the user has accepted the current active terms.

​
Check User’s Authorisation Status

curl --request GET \
  --url 'https://api.sandbox.goteal.co/authorisations?user_id=95a0e70b-fe02-4f47-aef9-2efff279df71' \
  --header 'X-API-KEY: <api-key>'

​
Validation Logic

Each authorisation record includes an is_valid field that indicates whether the authorisation is currently valid:
  • is_valid: true - Authorisation status is active AND the associated term is active
  • is_valid: false - Either authorisation is revoked OR the term has been deactivated
If is_valid is false because the term was deactivated, the user needs to re-authorise to the new term.

​
Re-authorisation Flow

When you update your terms, you can deactivate the old term using deactivate_previous: true (see Managing Active Terms). Users who accepted the deactivated term will need to re-authorise.

​
Flow

1. Create new term with deactivate_previous: true
   → Old term set to is_active: false
   → New term created with is_active: true

2. Check user's authorisation:
   - GET /authorisations?user_id={user_id}
   - If their term's is_active = false, they need re-authorisation

3. Prompt user to review and accept new terms

4. Record new authorisation:
   - POST /authorisations with new term_id

5. Old authorisation record preserved for audit trail

​
Example: Detecting Outdated Authorisation

# 1. Get current active term
curl --request GET \
  --url 'https://api.sandbox.goteal.co/authorisations/terms?authorisation_category=recurring&is_active=true' \
  --header 'X-API-KEY: <api-key>'

# 2. Get user's authorisations
curl --request GET \
  --url 'https://api.sandbox.goteal.co/authorisations?user_id=95a0e70b-fe02-4f47-aef9-2efff279df71' \
  --header 'X-API-KEY: <api-key>'

# 3. Compare: if user's term_id doesn't match current active term, prompt for re-authorisation

​
Revoking Authorisation

Users can revoke their authorisation at any time. Revocation preserves the record for audit purposes. 
curl --request PUT \
  --url https://api.sandbox.goteal.co/authorisations/7f3b8c2a-1d4e-5f6g-7h8i-9j0k1l2m3n4o/revoke \
  --header 'X-API-KEY: <api-key>'
After revocation:
  • The authorisation record’s status changes to revoked
  • The revoked_at timestamp is set
  • The record is preserved for compliance and audit purposes