Authorisations

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

Type	Description
System Terms	Default terms provided by Teal, available to all clients. Identified by `is_system_term: true`.
Custom Terms	Terms created by your organization for specific use cases. Identified by `is_system_term: false`.

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_previous`	Behavior
`false` (default)	New term is created. Existing active terms remain active.
`true`	New 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

Field	Behavior
`term_id`	Optional. If not provided, auto-resolves to the latest active term based on user’s recurring check configuration.
`ip_address`	Optional. 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
expires_at - Expiry timestamp for the authorisation. Present for one-time authorisations.
status - active, revoked, or expired

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 AND the authorisation has not expired
is_valid: false - Either authorisation is revoked, the term has been deactivated, or the authorisation has expired

If is_valid is false because the term was deactivated, the user needs to re-authorise to the new term.

One-time authorisations automatically expire. Once expired, the user must re-authorise before any further actions can be performed. Check the expires_at field on the authorisation record to see when it expires.

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

Get Started

Authorisations

Authorisation Terms

System Terms vs Custom Terms

Categories

Retrieving Available Terms

Creating Custom Terms

Managing Active Terms

Getting the Latest Term for a User

Recording Authorisation

Optional Fields

Authorisation Record

Validating Authorisation

Check User’s Authorisation Status

Validation Logic

Re-authorisation Flow

Flow

Example: Detecting Outdated Authorisation

Revoking Authorisation

​Authorisation Terms

​System Terms vs Custom Terms

​Categories

​Retrieving Available Terms

​Creating Custom Terms

​Managing Active Terms

​Getting the Latest Term for a User

​Recording Authorisation

​Optional Fields

​Authorisation Record

​Validating Authorisation

​Check User’s Authorisation Status

​Validation Logic

​Re-authorisation Flow

​Flow

​Example: Detecting Outdated Authorisation

​Revoking Authorisation

Authorisation Terms

System Terms vs Custom Terms

Categories

Retrieving Available Terms

Creating Custom Terms

Managing Active Terms

Getting the Latest Term for a User

Recording Authorisation

Optional Fields

Authorisation Record

Validating Authorisation

Check User’s Authorisation Status

Validation Logic

Re-authorisation Flow

Flow

Example: Detecting Outdated Authorisation

Revoking Authorisation