One-Time Links

Overview

One-time links provide maximum security for sensitive file sharing by becoming permanently inaccessible after a single use. This feature is ideal for sharing confidential documents, temporary passwords, or any content that should only be accessed once.

How One-Time Links Work

One-time links use a two-flag system to track usage:

Create access link with oneTimeUse: true
First access succeeds and sets used: true
All subsequent access attempts are denied
Link remains in database but becomes permanently inaccessible

The used flag is set after successful access, not during the check. This ensures the first access is always granted.

Data Model

One-time use is controlled by two boolean fields in the Access model (see models/access.go:15-16):

OneTimeUse bool `gorm:"default:false"` // Flag indicating if the link is one-time use
Used       bool `gorm:"default:false"` // Flag indicating if the link has been used

OneTimeUse - Enables single-use behavior when set to true
Used - Tracks whether the link has been accessed; set to true after first use

Creating One-Time Links

Prepare your file

Ensure the file you want to share is uploaded and you have its file ID.

Enable one-time use

Set oneTimeUse: true in your access creation request.

Configure additional restrictions

Optionally add IP restrictions, expiration, or other security measures.

Create and share

Generate the link and share it with your intended recipient.

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": "Confidential Document",
    "public": true,
    "oneTimeUse": true
  }'

Success Response

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

Notice OneTimeUse: true and Used: false - the link is ready for its single use.

Validation Logic

One-time use is validated in two stages during the access middleware (see middleware/access_restrictions.go:52-55 and 73-80):

Stage 1: Pre-Access Check

func checkOneTimeUse(access models.Access, c *gin.Context) bool {
    if access.OneTimeUse && access.Used {
        c.JSON(http.StatusForbidden, gin.H{"error": "Access link has already been used"})
        c.Abort()
        return false
    }
    return true
}

Process:

Check if OneTimeUse is true AND Used is true
If both true, deny access (link already used)
If Used is false, allow access to proceed

Stage 2: Post-Access Marking

if access.OneTimeUse {
    access.Used = true
    db.Save(&access)
}

Process:

After all checks pass and access is granted
If OneTimeUse is true, set Used to true
Save the updated access record to database
All future attempts will fail the pre-access check

The used flag is set immediately after the first successful access check, even before the file download completes. If the download is interrupted, the link is still marked as used.

Lifecycle Example

Let’s trace a one-time link through its complete lifecycle:

Initial Creation

{
  "OneTimeUse": true,
  "Used": false
}

Link is created and ready for its single use.

First Access Attempt

User clicks the link for the first time.Pre-access check:

OneTimeUse: true ✓
Used: false ✓
Check passes, access granted

Post-access:

{
  "OneTimeUse": true,
  "Used": true
}

Flag is immediately set to Used: true.

Second Access Attempt

Same or different user tries to access the link.Pre-access check:

OneTimeUse: true ✓
Used: true ✗
Check fails, access denied

Error:

{
  "error": "Access link has already been used"
}

All Future Attempts

{
  "OneTimeUse": true,
  "Used": true
}

Link remains permanently disabled. All attempts fail.

Error Response

When attempting to access a used one-time link:

{
  "error": "Access link has already been used"
}

HTTP Status: 403 Forbidden This error is permanent - once a one-time link is used, it cannot be reset through normal access.

To restore access, you must update the access record through the API (see “Resetting Used Links” below), or create a new access link.

Monitoring Link Usage

You can check if a one-time link has been used:

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

Response (unused):

{
  "access": {
    "ID": 19,
    "Name": "Confidential Document",
    "Link": "e6f5a1d2b4c789023defbc45678901ab",
    "OneTimeUse": true,
    "Used": false,
    "Public": true,
    "FileID": 42
  }
}

Response (used):

{
  "access": {
    "ID": 19,
    "Name": "Confidential Document",
    "Link": "e6f5a1d2b4c789023defbc45678901ab",
    "OneTimeUse": true,
    "Used": true,
    "Public": true,
    "FileID": 42
  }
}

The Used: true field indicates the link has been accessed.

Resetting Used Links

If you need to restore a used one-time link (e.g., first access failed to download), you can reset the used flag:

curl -X PUT https://your-defdrive-instance.com/access/19 \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Confidential Document",
    "public": true,
    "oneTimeUse": true
  }'

Updating an access record through the API does not automatically reset the used flag. The flag persists unless the access record is deleted and recreated.

To fully reset, delete and create a new access:

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

Combining with Other Restrictions

One-time links can be layered with other access controls for enhanced security:

One-Time + Expiration

{
  "oneTimeUse": true,
  "expires": "2026-03-05T23:59:59Z"
}

Behavior:

Link expires after first use, OR
Link expires on date (whichever comes first)

This ensures the link can’t remain unused indefinitely. If recipient doesn’t access within the timeframe, the link becomes inaccessible.

One-Time + IP Restrictions

{
  "oneTimeUse": true,
  "ips": ["203.0.113.45"],
  "subnets": ["192.168.1.0/24"]
}

Behavior:

Access only from allowed IPs/subnets, AND
Only once from any of those addresses

One-Time + TTL (Not Recommended)

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

Combining oneTimeUse with TTL is redundant. The oneTimeUse flag will cause the link to fail after first use, making the TTL setting irrelevant. Choose one or the other.

One-Time vs TTL

Both limit access, but work differently:

Feature	One-Time Use	TTL
Uses allowed	1	Configurable (any integer)
Configuration	`oneTimeUse: true`	`enableTTL: true` + `ttl: N`
Tracking	`used` boolean flag	Integer counter
Reset behavior	Cannot be reset (must delete)	Can be increased
When marked	After first access	Decrements during access
Best for	Maximum security, sensitive files	Multi-use limits, trial access

Implementation Difference:

// One-Time Use: Check then mark
if access.OneTimeUse && access.Used {
    // Deny
}
// ... grant access ...
access.Used = true

// TTL: Decrement then check
if access.EnableTTL && access.TTL > 0 {
    access.TTL--
    if access.TTL == 0 {
        // Deny
    }
}

Use Cases

Share temporary credentials securely:

{
  "name": "Admin Password",
  "oneTimeUse": true,
  "expires": "2026-03-04T15:00:00Z",
  "ips": ["203.0.113.45"]
}

Recipient can view password once, from specific IP, within 5 hours.

Legal Documents

Share contracts or NDAs for review:

{
  "name": "NDA for Review",
  "oneTimeUse": true,
  "expires": "2026-03-11T23:59:59Z"
}

Client can access document once within one week.

Secure File Transfers

Exchange sensitive files with partners:

{
  "name": "Q4 Financial Report",
  "oneTimeUse": true,
  "subnets": ["198.51.100.0/24"]
}

Partner can download once from their corporate network.

Audit Logs

Provide one-time access to audit reports:

{
  "name": "Security Audit 2026-Q1",
  "oneTimeUse": true,
  "expires": "2026-03-08T23:59:59Z"
}

Auditor can access report once before deadline.

Access Restrictions Order

The middleware checks restrictions in a specific order (see middleware/access_restrictions.go:44-50):

Subnet Restriction - Verify client IP in allowed subnets
IP Restriction - Verify client IP in allowed IPs
One-Time Use - Check if link already used
TTL - Decrement and check TTL counter
Expiration - Verify current time before expiration

All checks must pass for access to be granted.

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

if access.OneTimeUse {
    access.Used = true
    db.Save(&access)
}

If any check fails, subsequent checks are not performed and access is immediately denied.

Best Practices

Use for Sensitive Content - Reserve one-time links for truly confidential information
Add Expiration Dates - Combine with time limits to prevent indefinite unused links
Layer IP Restrictions - Add IP/subnet filters for maximum security
Test Before Sharing - Verify the link works, but remember it will be consumed
Monitor Usage - Check used flag to confirm recipient accessed the file
Create New for Retries - If first access fails, delete and recreate the link
Avoid TTL Combination - Don’t combine with TTL; use one or the other
Document Purpose - Use descriptive names to track why one-time was needed

Security Considerations

Important Security Notes:

Once a link is used, the used flag is set immediately, even if download is interrupted
If the first access fails (network error, etc.), the link is still marked as used
The link hash remains in the database permanently; only the used flag changes
Anyone with the link can use it first; there’s no recipient verification

For maximum security, combine one-time links with:

IP restrictions - Ensure only specific IP can access
Expiration - Limit the window of opportunity
Out-of-band communication - Share link via secure channel

Troubleshooting

”Link already used” but recipient never accessed

Possible causes:

Link preview bot/crawler accessed the link
Accidental click during testing
Malicious actor intercepted the link

Solution: Delete and recreate the access link with additional restrictions.

Need to allow second access

One-time links are permanent by design. Solution: Create a new one-time link or a TTL link with ttl: 2.

Monitoring who accessed

DefDrive doesn’t log access timestamps or IPs in the access record. Solution: Check server logs or implement custom logging middleware.

Next Steps

TTL Configuration - Limit access by number of uses
Creating Access Links - Learn about other access restrictions
IP Subnet Restrictions - Control access by network location

Get Started

Installation

Core Concepts

Guides

Overview

How One-Time Links Work

Data Model

Creating One-Time Links

API Examples

Success Response

Validation Logic

Stage 1: Pre-Access Check

Stage 2: Post-Access Marking

Lifecycle Example

Error Response

Monitoring Link Usage

Resetting Used Links

Combining with Other Restrictions

One-Time + Expiration

One-Time + IP Restrictions

One-Time + TTL (Not Recommended)

One-Time vs TTL

Use Cases

Legal Documents

Secure File Transfers

Audit Logs

Access Restrictions Order

Best Practices

Security Considerations

Troubleshooting

”Link already used” but recipient never accessed

Need to allow second access

Monitoring who accessed

Next Steps

Build docs developers (and LLMs) love

Get Started

Installation

Core Concepts

Guides

​Overview

​How One-Time Links Work

​Data Model

​Creating One-Time Links

​API Examples

​Success Response

​Validation Logic

​Stage 1: Pre-Access Check

​Stage 2: Post-Access Marking

​Lifecycle Example

​Error Response

​Monitoring Link Usage

​Resetting Used Links

​Combining with Other Restrictions

​One-Time + Expiration

​One-Time + IP Restrictions

​One-Time + TTL (Not Recommended)

​One-Time vs TTL

​Use Cases

​Password Sharing

​Legal Documents

​Secure File Transfers

​Audit Logs

​Access Restrictions Order

​Best Practices

​Security Considerations

​Troubleshooting

​”Link already used” but recipient never accessed

​Need to allow second access

​Monitoring who accessed

​Next Steps

Build docs developers (and LLMs) love

Overview

How One-Time Links Work

Data Model

Creating One-Time Links

API Examples

Success Response

Validation Logic

Stage 1: Pre-Access Check

Stage 2: Post-Access Marking

Lifecycle Example

Error Response

Monitoring Link Usage

Resetting Used Links

Combining with Other Restrictions

One-Time + Expiration

One-Time + IP Restrictions

One-Time + TTL (Not Recommended)

One-Time vs TTL

Use Cases

Password Sharing

Legal Documents

Secure File Transfers

Audit Logs

Access Restrictions Order

Best Practices

Security Considerations

Troubleshooting

”Link already used” but recipient never accessed

Need to allow second access

Monitoring who accessed

Next Steps