Change a Format grant role: PATCH run to write and back

Change a partner's access with PATCH /v1/formats/{handle}/{slug}/grants/{workspace} and a body of {"role":"run"} or {"role":"write"}. Raising to write takes effect on the grantee's next authoring call, and lowering to run closes the package immediately; no revoke and re-invite is needed.

What each role allows

The role field is required on this call. It works on pending grants as well as accepted ones, so you can fix a wrong role before the partner accepts.

run means the grantee can list, read, invoke and overlay the Format. write adds editing the package through the Contents API at your same {handle}/{slug} address, which is where the If-Match edit flow applies. Managing the roster is never part of either role.

curl -sS -X PATCH "https://api.sume.com/v1/formats/acme/product-promo/grants/kiwi" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role":"run"}'

Timing

A common sequence

Agencies often give a contractor write for a week while a Format is being tuned, then drop to run. Do that with two PATCH calls rather than a delete. A revoke would end invocation as well, and a re-invite would need a new accept.

Because edits happen at your own address, there is only ever one copy of the package. When the partner's edit lands, it is visible to you and to every other grantee at once, so reserve write for people you would let edit your own copy.

Checking the result

The PATCH returns the updated grant, so read the role field in the response before you tell the partner it changed. If you need to confirm the whole roster afterward, GET .../grants lists live grants newest first, pending and accepted together, and leaves out anything revoked.

Keep the call in a provisioning script that states the role you want for each partner, and read the grant in the response to confirm it.

Finally, use a team key from the owner workspace with formats:write. The same key that created the grant is the right one; a grantee's key cannot raise its own role.

Limits

A role change does not roll back edits made while the grantee held write. Undo any edit you do not want yourself. The call also cannot target a workspace that has no grant: that reads as not found.

There is no role finer than these two. If you want a partner to run but never see the instructions, this feature does not provide that; run includes read.