ロールを更新する
すべてのフィールドは任意で、`permissions` は一覧全体を置き換えます。
実際の呼び出しを、ご自身のキーで自分のワークスペースに対して実行します。
PATCH /roles/{id}
すべてのフィールドは任意で、permissions は一覧全体を置き換えます。
例
roles:write が必要です。フィールドを省略すればそのまま残ります。それが PATCH の意味です。
curl -X PATCH "$OE/roles/role_2b81de079c1f0a4b7e05d386" -H "$AUTH" \ -H "Content-Type: application/json" \ -d '{ "permissions": ["emails:read", "threads:read", "labels:read", "contacts:read"] }'{ "object": "role", "id": "role_2b81de079c1f0a4b7e05d386", "name": "Support", "description": "Answers the shared inboxes and nothing else.", "permissions": ["emails:read", "threads:read", "labels:read", "contacts:read"], "builtin": null, "editable": true, "deletable": true, "members": 3, "apiKeys": 1, "createdAt": "2026-08-30T10:41:02.000Z", "updatedAt": "2026-08-30T13:02:19.000Z"}permissions は一覧全体を置き換えます。1 件だけ付与する呼び出しはなく、今後も作りません。監査されるのは一覧であり、インデックス指定のパッチは、タブを 2 つ開いた瞬間に更新の消失になります。ロールを読み、目的のエントリを変更し、すべてを送り返してください。パーミッションを 1 つ送っても、パーミッションが 1 つ追加されるわけではありません。そのロールはそれ 1 つと、それが含意するものだけを持つ状態になります。
description は任意であるだけでなく null 許容でもあり、その違いこそがパッチの要点です。省略すれば保存された文がそのまま残り、null を送れば消えます。null 許容がなければ、説明を消すにはスペースに置き換えるしかありませんでした。
PATCH が拒否する唯一のロールはオーナーで、そのすべてのフィールドを拒否します。role_immutable、409 に param: "roleId" が付きます。それ以外はシードされたロールも含め、新しいパーミッション一覧と同じくらい気軽に新しい名前も受け付けます。builtin はロールの出自を記録するものであって、何をしてよいかを記録するものではありません。別のロールがすでに持っている名前の場合は role_name_taken になり、409 に param: "name" が付きます。
この編集は、そのロールを持つ誰か（API キーを含む）が次に行うリクエストから反映されます。上限はキャッシュされず、リクエストごとに解決されるからです。したがってロールを狭めることは、その下のキーをローテーションしなくても効く即時の失効になります。広げるほうも同じく即時であり、そちらが覚えておく価値のある半面です。