Deep Dive: UCAN Authorization for Research Collaboration

Understanding UCAN

The difference between UCAN and an API key is where the authority lives.

An API key is a lookup handle. It means nothing on its own; the server holds a table mapping it to a set of permissions, and every check is a query against that table. OAuth adds structure to how the handle is obtained, but the shape is the same - the issuing server remains the arbiter, and it has to be reachable and consulted for anything to be decided.

A UCAN carries its authority inside itself. The token states who issued it, who it is for, exactly what it permits, and when it expires, and it is signed. A verifier checks the signature and reads the terms. Nothing is looked up, so nothing has to be online.

That single change is what makes delegation work. Because the token is the authority rather than a pointer to it, its holder can mint a narrower token for someone else and sign it with their own key - no coordination with whoever issued the original, and no account provisioned anywhere. The chain of who granted what to whom is the token itself.

The cost is the mirror image: revocation stops being instant. A key you delete from a table is dead on the next request, whereas a signed token is valid until it expires or a verifier learns it was revoked. That trade - offline verification bought with weaker revocation - is the whole design decision, and it is why short expiries matter more here than they do with API keys.

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:devnet:FWePP4F42jYMNguSBjVsTszizNufYrwKkmN7BAZ1sMS6",
        "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:devnet:2wF3um4yXLZcD8LjMng1QiNb3kLNzJpabz7EriffgibT' },
    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:devnet:2wF3um4yXLZcD8LjMng1QiNb3kLNzJpabz7EriffgibT' },
    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.