Skip to main content

​
Overview

Access links provide a secure way to share files with others without requiring them to have a DefDrive account. Each access link is a unique MD5-style hash that grants access to a specific file with configurable restrictions. Access links are 32-character hexadecimal strings that look like MD5 hashes: 
https://your-defdrive-instance.com/a3f2c8b9e1d4567890abcdef12345678
The link generation algorithm ensures uniqueness by checking the database for collisions (see controllers/access.go:26-39).
1

Identify your file

Get the file ID from your uploaded files. You must own the file to create access links for it.
2

Configure access settings

Decide on restrictions: IP allowlists, subnet restrictions, expiration, one-time use, and TTL settings.
3

Send create request

POST to /files/:fileID/access with your configuration.
4

Share the link

Distribute the generated link to authorized users.

​
API Request

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

​
Request Parameters

ParameterTypeRequiredDescription
namestringNoHuman-readable identifier for the access link
publicbooleanYesMust be true for link to be accessible
ipsstring[]NoArray of allowed IP addresses
subnetsstring[]NoArray of allowed CIDR subnets
expiresstringNoRFC3339 timestamp for link expiration
oneTimeUsebooleanNoIf true, link becomes invalid after first use
enableTTLbooleanNoEnable TTL-based access limitation
ttlintegerNoNumber of times link can be accessed (when enableTTL is true)
All access control fields are defined in models/access.go:7-22. The public flag must be true for the link to be accessible.

​
Success Response

{
  "message": "Access created successfully",
  "access": {
    "ID": 15,
    "CreatedAt": "2026-03-04T10:30:00Z",
    "UpdatedAt": "2026-03-04T10:30:00Z",
    "DeletedAt": null,
    "Name": "Client Preview Link",
    "Link": "a3f2c8b9e1d4567890abcdef12345678",
    "Subnets": [],
    "IPs": [],
    "Expires": "",
    "Public": true,
    "OneTimeUse": false,
    "Used": false,
    "TTL": 0,
    "EnableTTL": false,
    "FileID": 42
  },
  "link": "https://your-defdrive-instance.com/a3f2c8b9e1d4567890abcdef12345678"
}
The link field provides the complete URL ready to share with users. The system generates unique access links using the following process (see controllers/access.go:26-39):
  1. Create MD5 hash from UUID + current timestamp
  2. Check database for collision
  3. If collision exists, regenerate
  4. Return unique 32-character hexadecimal string
The collision check ensures every access link is globally unique across your DefDrive instance.

​
Public Access Requirement

Both the file and the access record must have public: true for the link to work. If either is false, access will be denied with “Access denied: file or access is not public” error.
This dual-flag system is enforced in middleware/access_restrictions.go:37-41: 
if !(file.Public && access.Public) {
    c.JSON(http.StatusForbidden, gin.H{"error": "Access denied: file or access is not public"})
    c.Abort()
    return
}
To make a file publicly accessible: 
curl -X PUT https://your-defdrive-instance.com/files/42/public \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"public": true}'

curl -X GET https://your-defdrive-instance.com/files/42/access \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"
Response: 
{
  "accesses": [
    {
      "ID": 15,
      "Name": "Client Preview Link",
      "Link": "a3f2c8b9e1d4567890abcdef12345678",
      "Public": true,
      "OneTimeUse": false,
      "Used": false,
      "Expires": "2026-12-31T23:59:59Z",
      "FileID": 42
    },
    {
      "ID": 16,
      "Name": "Internal Share",
      "Link": "b4e3d9c0f2e5678901bcdefg23456789",
      "Public": true,
      "OneTimeUse": true,
      "Used": false,
      "FileID": 42
    }
  ]
}

curl -X PUT https://your-defdrive-instance.com/access/15 \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Client Link",
    "public": true,
    "expires": "2027-06-30T23:59:59Z"
  }'

curl -X DELETE https://your-defdrive-instance.com/access/15 \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"
Response: 
{
  "message": "Access deleted successfully"
}

​
Authorization

Access link operations require ownership verification (see controllers/access.go:55-65):
  1. System verifies you own the file
  2. Only file owners can create, update, or delete access links
  3. Attempting to manage another user’s file access returns 403 Forbidden

​
Error Responses

​
File Not Found

{
  "error": "File not found"
}

​
Unauthorized Access

{
  "error": "You don't have permission to create access for this file"
}

​
Invalid Request Body

{
  "error": "Invalid request body"
}

​
Environment Configuration

The full access URL is constructed using the HOST_URL environment variable (see controllers/access.go:106-111): 
HOST_URL=https://your-defdrive-instance.com
Ensure this is properly configured in your deployment for correct link generation.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us