TTL Configuration

Overview

TTL (Time To Live) provides a usage-based access control mechanism that decrements with each access attempt. Unlike expiration dates which are time-based, TTL limits access by counting the number of times a link is used.

How TTL Works

TTL implements a hop-count system where each successful access decrements the TTL counter:

Create access link with enableTTL: true and ttl: N
Each successful access decrements the TTL value by 1
When TTL reaches 0, the link becomes permanently inaccessible
TTL is checked before content is served

TTL is decremented during the access check, not after download completes. If TTL reaches 0 during access, that final access is denied.

Data Model

TTL is controlled by two fields in the Access model (see models/access.go:17-18):

TTL        int  `gorm:"default:0"`     // Time to live (number of hops)
EnableTTL  bool `gorm:"default:false"` // Flag to enable or disable TTL

EnableTTL - Master switch that activates TTL checking
TTL - Integer counter representing remaining accesses allowed

Creating TTL-Limited Links

Determine access count

Decide how many times the file should be accessible.

Enable TTL

Set enableTTL: true in your access creation request.

Set TTL value

Specify the initial counter value in the ttl field.

Create access link

Send the request with TTL configuration.

API Examples

curl -X POST https://your-defdrive-instance.com/files/42/access \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Limited Preview",
    "public": true,
    "enableTTL": true,
    "ttl": 5
  }'

Success Response

{
  "message": "Access created successfully",
  "access": {
    "ID": 18,
    "CreatedAt": "2026-03-04T10:30:00Z",
    "UpdatedAt": "2026-03-04T10:30:00Z",
    "DeletedAt": null,
    "Name": "Limited Preview",
    "Link": "d5e4f0c1a3b6789012cdefab34567890",
    "Subnets": [],
    "IPs": [],
    "Expires": "",
    "Public": true,
    "OneTimeUse": false,
    "Used": false,
    "TTL": 5,
    "EnableTTL": true,
    "FileID": 42
  },
  "link": "https://your-defdrive-instance.com/d5e4f0c1a3b6789012cdefab34567890"
}

Notice the TTL: 5 and EnableTTL: true fields in the response.

TTL Validation Logic

The TTL check is performed during access validation in the middleware (see middleware/access_restrictions.go:113-124):

func checkTTL(access models.Access, db *gorm.DB, c *gin.Context) bool {
    if access.EnableTTL && access.TTL > 0 {
        access.TTL--
        if access.TTL == 0 {
            c.JSON(http.StatusForbidden, gin.H{"error": "Access link has reached its TTL limit"})
            c.Abort()
            return false
        }
        db.Save(&access)
    }
    return true
}

Process:

Check if EnableTTL is true and TTL > 0
Decrement TTL counter by 1
If TTL reaches 0, deny access and abort
If TTL > 0, save new value and allow access
If EnableTTL is false, skip TTL check entirely

When TTL reaches 0, the link is permanently disabled. The access record remains in the database but can never be used again.

TTL Lifecycle Example

Let’s trace a TTL-3 link through its lifecycle:

Initial Creation

{
  "TTL": 3,
  "EnableTTL": true
}

Link is created with 3 uses remaining.

First Access

User accesses link, TTL decrements to 2.

{
  "TTL": 2,
  "EnableTTL": true
}

Access granted. 2 uses remaining.

Second Access

User accesses link again, TTL decrements to 1.

{
  "TTL": 1,
  "EnableTTL": true
}

Access granted. 1 use remaining.

Third Access

User accesses link, TTL decrements to 0.

{
  "TTL": 0,
  "EnableTTL": true
}

Access DENIED. Error: “Access link has reached its TTL limit”

Further Attempts

{
  "TTL": 0,
  "EnableTTL": true
}

All subsequent access attempts fail. Link is permanently disabled.

The third access attempt is denied because the TTL reaches 0 during that request. Only the first two accesses succeed.

Error Response

When TTL reaches its limit:

{
  "error": "Access link has reached its TTL limit"
}

HTTP Status: 403 Forbidden This error is permanent - the link can never be used again unless you update the TTL value through the API.

Monitoring TTL Usage

You can check the current TTL value of an access link:

curl -X GET https://your-defdrive-instance.com/access/18 \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

Response:

{
  "access": {
    "ID": 18,
    "Name": "Limited Preview",
    "Link": "d5e4f0c1a3b6789012cdefab34567890",
    "TTL": 2,
    "EnableTTL": true,
    "Public": true,
    "FileID": 42
  }
}

The TTL: 2 indicates 2 accesses remaining.

Updating TTL

You can modify the TTL value or enable/disable TTL on existing access links:

curl -X PUT https://your-defdrive-instance.com/access/18 \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Limited Preview",
    "public": true,
    "enableTTL": true,
    "ttl": 10
  }'

You can restore a depleted TTL link by updating the TTL to a new positive value.

TTL vs One-Time Use

Both TTL and OneTimeUse limit access, but they work differently:

Feature	TTL	One-Time Use
Use count	Configurable (any integer)	Always 1
Requires enable flag	Yes (`enableTTL`)	No
Decrements	During access	After access
Edge case	Denied when reaches 0	Allowed on first, denied on second
Database field	Two fields (`TTL`, `EnableTTL`)	Two fields (`OneTimeUse`, `Used`)

TTL Implementation:

if access.EnableTTL && access.TTL > 0 {
    access.TTL--
    if access.TTL == 0 {
        // Deny access
    }
}

OneTimeUse Implementation:

if access.OneTimeUse && access.Used {
    // Deny access
}
// ... later, after successful access ...
if access.OneTimeUse {
    access.Used = true
}

Setting ttl: 1 with enableTTL: true is similar to oneTimeUse: true, but OneTimeUse is more explicit for single-use scenarios.

Combining TTL with Other Restrictions

TTL can be layered with other access controls for comprehensive security:

TTL + Expiration

{
  "enableTTL": true,
  "ttl": 10,
  "expires": "2026-12-31T23:59:59Z"
}

Link expires when either:

TTL reaches 0, OR
Current time exceeds expiration date

TTL + IP Restrictions

{
  "enableTTL": true,
  "ttl": 5,
  "ips": ["203.0.113.45"],
  "subnets": ["192.168.1.0/24"]
}

Link accessible only when:

Client IP matches restrictions, AND
TTL > 0 (if EnableTTL is true)

TTL + One-Time Use

{
  "enableTTL": true,
  "ttl": 3,
  "oneTimeUse": true
}

Combining TTL with OneTimeUse is redundant and not recommended. Use OneTimeUse for single-use links, or use TTL for multi-use limits.

Use Cases

Trial Downloads

Allow users to download a file multiple times during evaluation:

{
  "name": "Trial Document",
  "enableTTL": true,
  "ttl": 5,
  "expires": "2026-03-11T23:59:59Z"
}

User can download 5 times within one week.

Team Collaboration

Share a file with a small team, limiting total accesses:

{
  "name": "Team Resource",
  "enableTTL": true,
  "ttl": 20,
  "subnets": ["192.168.1.0/24"]
}

Up to 20 accesses from office network.

API Rate Limiting

Limit programmatic access to files:

{
  "name": "API Access",
  "enableTTL": true,
  "ttl": 100
}

Allow up to 100 API calls to fetch the file.

Content Preview

Allow limited previews before requiring payment:

{
  "name": "Preview Access",
  "enableTTL": true,
  "ttl": 3,
  "expires": "2026-03-05T23:59:59Z"
}

User can preview file 3 times in 24 hours.

Implementation Reference

The TTL check is part of the access restrictions middleware pipeline (see middleware/access_restrictions.go:44-50):

if !checkSubnetRestriction(access, c) ||
    !checkIPRestriction(access, c) ||
    !checkOneTimeUse(access, c) ||
    !checkTTL(access, db, c) ||
    !checkExpiration(access, c) {
    return
}

All checks must pass for access to be granted. The order ensures:

Network restrictions verified first
Usage limits (OneTimeUse, TTL) checked
Time-based expiration validated last

Best Practices

Set Appropriate Values - Consider use case: 1-5 for limited sharing, 10-100 for team access
Combine with Expiration - Use both TTL and expiration date for comprehensive control
Monitor Usage - Check TTL values periodically to understand access patterns
Document Purpose - Use descriptive name field to track why TTL was set
Reset When Needed - Update TTL if legitimate users need more access
Avoid TTL + OneTimeUse - Choose one or the other, not both
Test Before Sharing - Verify TTL decrements correctly by testing access

Next Steps

One-Time Links - Create single-use access links
Creating Access Links - Learn about other access restrictions
IP Subnet Restrictions - Control access by network location

Get Started

Installation

Core Concepts

Guides

TTL Configuration

Overview

How TTL Works

Data Model

Creating TTL-Limited Links

API Examples

Success Response

TTL Validation Logic

TTL Lifecycle Example

Error Response

Monitoring TTL Usage

Updating TTL

TTL vs One-Time Use

Combining TTL with Other Restrictions

TTL + Expiration

TTL + IP Restrictions

TTL + One-Time Use

Use Cases

Trial Downloads

Team Collaboration

API Rate Limiting

Content Preview

Implementation Reference

Best Practices

Next Steps

Build docs developers (and LLMs) love

Get Started

Installation

Core Concepts

Guides

​Overview

​How TTL Works

​Data Model

​Creating TTL-Limited Links

​API Examples

​Success Response

​TTL Validation Logic

​TTL Lifecycle Example

​Error Response

​Monitoring TTL Usage

​Updating TTL

​TTL vs One-Time Use

​Combining TTL with Other Restrictions

​TTL + Expiration

​TTL + IP Restrictions

​TTL + One-Time Use

​Use Cases

​Trial Downloads

​Team Collaboration

​API Rate Limiting

​Content Preview

​Implementation Reference

​Best Practices

​Next Steps

Build docs developers (and LLMs) love

Overview

How TTL Works

Data Model

Creating TTL-Limited Links

API Examples

Success Response

TTL Validation Logic

TTL Lifecycle Example

Error Response

Monitoring TTL Usage

Updating TTL

TTL vs One-Time Use

Combining TTL with Other Restrictions

TTL + Expiration

TTL + IP Restrictions

TTL + One-Time Use

Use Cases

Trial Downloads

Team Collaboration

API Rate Limiting

Content Preview

Implementation Reference

Best Practices

Next Steps