References API

Overview

References (refs) are shareable tokens for various workflows including file sharing, email verification, password reset, and invitations. They support configurable expiration, usage limits, and access levels.

Endpoints

List References

GET /api/refs

List references for the current tenant.

Authentication: Required

Query Parameters:

Parameter Type Required Description
type string No Filter by type (e.g., share.file, email-verify)
filter string No Status filter: active, used, expired, all (default: active)
resourceId string No Filter by resource ID (e.g., file ID)

Response:

{
  "data": [
    {
      "refId": "abc123def456",
      "type": "share.file",
      "description": "Project document",
      "createdAt": 1735000000,
      "expiresAt": 1735604800,
      "count": null,
      "resourceId": "f1~xyz789",
      "accessLevel": "read"
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 10,
    "total": 1
  },
  "time": 1735000000,
  "reqId": "req_abc123"
}

Example:

// List all active file shares
const shares = await api.refs.list({
  type: 'share.file',
  filter: 'active'
})

// List shares for a specific file
const fileShares = await api.refs.list({
  resourceId: 'f1~xyz789'
})

Create Reference

POST /api/refs

Create a new reference token.

Authentication: Required

Request:

{
  "type": "share.file",
  "description": "Project document",
  "expiresAt": 1735604800,
  "count": null,
  "resourceId": "f1~xyz789",
  "accessLevel": "read"
}
Field Type Required Description
type string Yes Reference type
description string No Human-readable description
expiresAt number No Expiration timestamp (Unix seconds)
count number/null No Usage count: omit for 1, null for unlimited, or number
resourceId string No Resource ID (required for share.file)
accessLevel string No Access level: read or write (default: read)

Response:

{
  "data": {
    "refId": "abc123def456",
    "type": "share.file",
    "description": "Project document",
    "createdAt": 1735000000,
    "expiresAt": 1735604800,
    "count": null,
    "resourceId": "f1~xyz789",
    "accessLevel": "read"
  },
  "time": 1735000000,
  "reqId": "req_abc123"
}

Example:

// Create a read-only share link with unlimited uses
const shareLink = await api.refs.create({
  type: 'share.file',
  description: 'Team document',
  resourceId: 'f1~xyz789',
  accessLevel: 'read',
  count: null  // Unlimited uses
})

// Create a write-access share link (single use)
const editLink = await api.refs.create({
  type: 'share.file',
  resourceId: 'f1~xyz789',
  accessLevel: 'write'
  // count omitted = single use
})

Get Reference

GET /api/refs/{refId}

Get details of a specific reference. Returns full details if authenticated, minimal details (only refId and type) if not.

Authentication: Optional

Path Parameters:

Parameter Type Description
refId string Reference ID

Response (authenticated):

{
  "data": {
    "refId": "abc123def456",
    "type": "share.file",
    "description": "Project document",
    "createdAt": 1735000000,
    "expiresAt": 1735604800,
    "count": 5,
    "resourceId": "f1~xyz789",
    "accessLevel": "read"
  },
  "time": 1735000000,
  "reqId": "req_abc123"
}

Response (unauthenticated):

{
  "data": {
    "refId": "abc123def456",
    "type": "share.file"
  },
  "time": 1735000000,
  "reqId": "req_abc123"
}

Delete Reference

DELETE /api/refs/{refId}

Delete/revoke a reference. The reference will immediately become invalid.

Authentication: Required

Path Parameters:

Parameter Type Description
refId string Reference ID to delete

Response:

{
  "data": null,
  "time": 1735000000,
  "reqId": "req_abc123"
}

Guest Access with References

References can be used to grant guest access to resources without requiring authentication.

Exchange Reference for Access Token

GET /api/auth/access-token

Exchange a reference for a scoped access token. This enables unauthenticated users to access shared resources.

Authentication: None

Query Parameters:

Parameter Type Required Description
ref string Yes Reference ID

Response:

{
  "data": {
    "token": "eyJhbGc...",
    "expiresAt": 1735086400,
    "accessLevel": "read",
    "resourceId": "f1~xyz789"
  },
  "time": 1735000000,
  "reqId": "req_abc123"
}

Example:

// Guest accessing a shared file
const { token, accessLevel } = await api.auth.getAccessToken({
  ref: 'abc123def456'
})

// Use token for subsequent API calls
const file = await api.files.get('f1~xyz789', {
  headers: { 'Authorization': `Bearer ${token}` }
})

Reference Types

Type Description Requires resourceId
share.file File sharing link Yes
email-verify Email verification No
password-reset Password reset link No
invite User invitation No
welcome Welcome/onboarding link No

Usage Count Behavior

The count field controls how many times a reference can be used:

Value Behavior
Omitted Single use (default = 1)
null Unlimited uses
Number That many uses remaining

Each use decrements the count. When count reaches 0, the reference becomes invalid.

Access Levels

For share.file references, the accessLevel controls permissions:

Level Description
read View-only access (default)
write Edit access to the resource

Complete File Sharing Example

// 1. Create a shareable link
const share = await api.refs.create({
  type: 'share.file',
  description: 'Quarterly report',
  resourceId: 'f1~xyz789',
  accessLevel: 'read',
  count: null,  // Unlimited
  expiresAt: Math.floor(Date.now() / 1000) + 7 * 24 * 60 * 60  // 1 week
})

// 2. Generate share URL
const shareUrl = `https://example.cloudillo.net/share/${share.data.refId}`

// 3. Guest accesses the share (on their side)
const { token } = await fetch('/api/auth/access-token?ref=' + refId)
  .then(r => r.json())
  .then(r => r.data)

// 4. Guest uses token to access file
const file = await fetch('/api/files/f1~xyz789', {
  headers: { 'Authorization': `Bearer ${token}` }
})

See Also