Deep Dive: UCAN Authorization for Research Collaboration

Understanding UCAN

User Controlled Authorization Networks (UCAN) represent a paradigm shift in how we think about permissions and access control. Unlike traditional OAuth or API key systems, UCANs are:

• Decentralized: No central authority required for verification
• Delegatable: Permissions can be passed along a chain of trust
• Offline-verifiable: No network requests needed to validate
• Fine-grained: Precise control over what actions are allowed

Why UCAN for Research?

Research collaboration often involves complex permission hierarchies:

• Principal investigators need full access
• Lab managers need administrative capabilities
• Graduate students need read/write access to specific datasets
• External collaborators need time-limited read access

Traditional systems struggle with this complexity. UCAN makes it natural.

UCAN Structure

A UCAN token contains:

{
  "header": {
    "alg": "EdDSA",
    "typ": "JWT",
    "ucv": "0.10.0"
  },
  "payload": {
    "iss": "did:key:z6Mkr5aefin1DzjG7MBJ3nsFCsnvHKEvTb2C4YAJwbxt1jFS",
    "aud": "did:key:z6MkfQhLHBSFMuR7bQXTQeqe5kYUW51HpfZeaymgy1zkP2jM",
    "exp": 9256939505,
    "att": [
      {
        "with": "did:bio:dataset-123",
        "can": { "namespace": "biodata", "segments": ["read", "write"] }
      }
    ],
    "prf": []
  }
}

Delegation Chains

The real power of UCAN comes from delegation. Here's how it works in practice:

// Principal Investigator creates initial UCAN
const piUCAN = await build({
  issuer: piKeypair,
  audience: labManagerDID,
  capabilities: [{
    with: { scheme: 'did', hierPart: 'did:bio:project-123' },
    can: { namespace: 'biodata', segments: ['read', 'write', 'admin'] }
  }]
});

// Lab Manager delegates to Graduate Student
const studentUCAN = await build({
  issuer: labManagerKeypair,
  audience: studentDID,
  capabilities: [{
    with: { scheme: 'did', hierPart: 'did:bio:project-123' },
    can: { namespace: 'biodata', segments: ['read', 'write'] }
  }],
  proofs: [piUCAN] // Chain of trust
});

Best Practices

• Minimize capability scope: Grant only the permissions needed
• Set appropriate expiration: Use short-lived tokens for sensitive operations
• Maintain proof chains: Keep parent UCANs for audit trails
• Rotate keys regularly: Update keypairs periodically

Learn more in our UCAN Authorization documentation.