> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tinycloud.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Delegations & Sharing

> Grant scoped TinyCloud access to another principal.

Use this guide to grant another signed-in TinyCloud principal access to a path
in your space. In the examples, `alice` and `bob` are SDK instances that have
already completed `signIn()`.

## Create and use a delegation

Use the recipient's owner DID. After wallet sign-in, `bob.did` is that owner
DID; `bob.sessionDid` identifies the ephemeral session key instead.

```typescript theme={null}
const delegation = await alice.createDelegation({
  delegateDID: bob.did,
  path: "shared/",
  actions: ["tinycloud.kv/get", "tinycloud.kv/put"],
  expiryMs: 7 * 24 * 60 * 60 * 1000,
});

// Deliver `delegation` to Bob through your authenticated application channel.
const access = await bob.useDelegation(delegation);
const value = await access.kv.get("document.json");

if (!value.ok) throw new Error(value.error.message);
console.log(value.data.data);
```

`useDelegation()` returns a `DelegatedAccess` handle for the delegator's space.
Its KV service is already rooted at `shared/`, so its keys are relative to that
delegated path. It does not copy the data into the recipient's space.

## Serialize for transport

`createDelegation()` returns a `PortableDelegation` object. To send it as text,
use the SDK helpers instead of manually converting its `Date` fields:

```typescript theme={null}
import {
  serializeDelegation,
  deserializeDelegation,
} from "@tinycloud/node-sdk";

const payload = serializeDelegation(delegation);
// Send `payload` through an authenticated channel.

const received = deserializeDelegation(payload);
const receivedAccess = await bob.useDelegation(received);
```

The same helpers are exported by `@tinycloud/web-sdk` for browser applications.
The serialized delegation is a bearer credential; do not log it or send it
through an untrusted channel.

## Narrow access further

If the parent permits sub-delegation, Bob can grant Carol a narrower subset:

```typescript theme={null}
const child = await bob.createSubDelegation(delegation, {
  delegateDID: carol.did,
  path: "shared/public/",
  actions: ["tinycloud.kv/get"],
  expiryMs: 24 * 60 * 60 * 1000,
  disableSubDelegation: true,
});
```

The child must stay within the parent's resources and action set, cannot
outlive the parent, and cannot bypass a parent's sub-delegation restriction.

## Revoke access

Both the Node and Web SDKs expose `revokeDelegation()`:

```typescript theme={null}
const revoked = await alice.revokeDelegation(delegation.cid);
if (!revoked.ok) throw new Error(revoked.error.message);
```

Revocation is node-confirmed and invalidates use of that delegation. Revoking
an ancestor also prevents its descendants from being used. The Node SDK can
query the node-confirmed lifecycle state:

```typescript theme={null}
const status = await alice.getDelegationStatus(delegation.cid);
if (status.ok) console.log(status.data.status); // "revoked"
```

Delegations also stop working at their signed expiry. Expiry limits exposure,
but it is not a substitute for `revokeDelegation()` when access must end now.

## Inspect received grants

The Node SDK records delegations installed by `useDelegation()`:

```typescript theme={null}
const receivedDelegations = bob.delegations.list();
const oneDelegation = bob.delegations.get(delegation.cid);
```

For the SDK transport fields and the node's validation model, see
[Delegations](/reference/protocol/delegations).