> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goteal.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Authorisations

> Manage user authorisation for data sharing and access

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`. |

### 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). One-time authorisations expire after 1 day, after which the user must re-authorise.
* **recurring** - Ongoing authorisation for continuous data access (e.g., recurring payroll checks)

### Retrieving Available Terms

```bash theme={null}
curl --request GET \
  --url 'https://api.sandbox.goteal.co/authorisations/terms' \
  --header 'X-API-KEY: <api-key>'
```

Filter by type using query parameters:

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
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](#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:

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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.

<Note>
  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.
</Note>

## Re-authorisation Flow

When you update your terms, you can deactivate the old term using `deactivate_previous: true` (see [Managing Active Terms](#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

```bash theme={null}
# 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.

```bash theme={null}
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