latestOpenAPI 3.1.02026-08-218667571.2 MB

a8ca30023371

Admin APIs
ledger

Create S3 Grant

Award S3 tokens to a client, writing the grant and its full vesting schedule.

Credits nothing here — the vesting executor posts each period's credit when its vest_at arrives, including an immediate grant's single already-due period. That keeps every S3 credit on one code path with one idempotency anchor.

Returns the grant_id so the UI can link to the award it just created, and replays safely: the same idempotency key returns the stored grant with already_existed=true and writes nothing.

Naming a block_request_id whose contract does not exist yet holds the award awaiting_contract with no vesting rows: there is no billing anchor until the contract starts, and the subscription webhook builds the schedule then. Such a response carries effective_at: null and vesting_count: 0.

post/api/v1/admin/ledger/s3-grants

Request body

client_idstring required
order_idstring required
reasonstring required
vesting_kind'immediate' | 'monthly_12'

How a grant releases its tokens.

effective_atstring date-time nullable
block_contract_idstring uuid nullable
block_request_idstring uuid nullable
auto_applyboolean nullable
idempotency_keystring nullable
metadataobject

Response

Successful Response

grant_idstring uuid required
client_idstring uuid required
order_idstring required
statusstring required
vesting_kindstring required
allocatedstring required
effective_atstring date-time nullable
block_contract_idstring uuid nullable
block_request_idstring uuid nullable
auto_applyboolean
vesting_countinteger required
already_existedboolean required