Grants
The access ledger as a connector may read and write it — finding a grant by id or by the reference you issued, what a summary tells you, and when a connector records a grant itself.
Subscriby\Connector\Core\Grants. The ledger is the core's record of who should be where: one grant per subscription, resource and pass window, with a mode, a state and the reference your AccessController issued. The connector holds the platform's side (the invite link, the role); this contract lets it read the ledger by that reference and, in a migration, write to it.
Reads
| Method | Returns | Null when |
|---|---|---|
find(string $id) | ?GrantSummary | No grant has that UUID. |
findByReference(string $connector, string $reference) | ?GrantSummary | The connector never issued that reference. |
findByReference() is how a join request finds the purchase behind the link it arrived on: the platform tells you which invite link was used, the ledger tells you whose grant it is and whether it is still granted, held or already revoked, and your handler admits or refuses accordingly. It works for any mode whose reference is unique per connector (a bearer_link); a role reference may repeat across concurrent subscriptions and is read by id instead.
GrantSummary
| Field | Meaning |
|---|---|
id | The grant row. |
projectId, subscriptionId, resourceId, windowId | Whose access, to what, for which pass window (null outside passes). |
mode | GrantMode: BearerLink, Membership, Role, CreatorTask. |
state | GrantState: PendingIdentity, Pending, Held, Granted, Revoked, Failed. |
identityId | The account that holds it, null while it waits for one. |
connector, reference | Your connector and what you issued. |
grantedAt, revokedAt | When. |
The states
| State | Means |
|---|---|
PendingIdentity | The purchase is settled but the member has no identity on this connector yet; materialises when one is linked. |
Pending | The grant is being issued. |
Held | Pre-issued for a pass whose window has not opened; released by admit(). |
Granted | Live. |
Revoked | Ended: cancelled, expired, paused, banned, uninstalled, or superseded by a reissue. |
Failed | The connector could not issue it; the failure kind is on the row and the creator is shown a creator-actionable one. |
record()
$ref = $grants->record(new GrantRecord(
subscriptionId: $subscription->id,
resourceId: $resource->id,
mode: GrantMode::BearerLink,
state: GrantState::Granted,
windowId: null,
identityId: $identity->id,
connector: 'example',
reference: $inviteLink,
payload: [],
grantedAt: $issuedAt,
));Idempotent on the subscription, the resource and the window: it writes the grant or rewrites the one the purchase already holds for that resource and date. The core writes grants itself from your AccessController::grant() result, so a connector calls record() directly only when it learns of a grant outside that flow.
Read the ledger, never your own copy
A connector that keeps its own "who is in" table will disagree with the ledger the first time a subscription is paused from the dashboard. Keep the reference; ask the ledger.
How is this guide?
Resources
The resource rows as a connector may read them, and the one write — selling access to a place a creator picked — with its idempotency, its authorisation, its refusals and what the core announces.
Creators
Creator accounts as a connector may create them — the one call that turns a connector's sign-up form into an email-first account with a linked identity, and the two ways it is refused.