Update API Key Scopes - Terminal Use

PATCH

api_keys

{api_key_id}

Update API Key Scopes

curl --request PATCH \
  --url https://api.example.com/api_keys/{api_key_id} \
  --header 'Content-Type: application/json' \
  --data '
{
  "scopes": [
    {
      "resource_id": "<string>",
      "resource_type": "<string>"
    }
  ]
}
'

{
  "created_by": "<string>",
  "id": "<string>",
  "key_prefix": "<string>",
  "name": "<string>",
  "org_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "last_used_at": "2023-11-07T05:31:56Z",
  "revoked_at": "2023-11-07T05:31:56Z",
  "scopes": [
    {
      "resource_id": "<string>",
      "resource_type": "<string>"
    }
  ],
  "sharing_group_ids": [
    "<string>"
  ]
}

Each scope grants a role on a specific resource:

{
  "resource_type": "agent",
  "resource_id": "agt_xxx",
  "role": "editor"
}

Valid Roles by Resource Type

Resource Type	Valid Roles
`org`	`admin`, `member`
`namespace`	`admin`
`project`	`discoverer`, `viewer`, `editor`, `owner`
`agent`	`discoverer`, `viewer`, `editor`, `owner`, `executor`

The executor role is legacy and is normalized to viewer internally, but still grants run permission.

Path Parameters

api_key_id

string

required

Body

application/json

Request model for updating API key scopes.

scopes

ApiKeyScope · object[]

required

Updated list of resource scopes.

Minimum array length: 1

Show child attributes

Response

Successful Response

Response model for API key (excludes sensitive data).

created_by

string

required

member_id of the creator.

string

required

The unique identifier of the API key.

key_prefix

string

required

Display prefix (e.g., 'sk_tu_abc...').

name

string

required

Human-readable name for the API key.

org_id

string

required

WorkOS organization ID.

created_at

string<date-time> | null

When the key was created.

description

string | null

Optional description.

last_used_at

string<date-time> | null

When the key was last used.

revoked_at

string<date-time> | null

When the key was revoked (soft delete).

scopes

ApiKeyScope · object[]

List of resource scopes for this API key.

Show child attributes

Groups that receive default admin grants on resources created by this key.

Update API Key Sharing GroupsUpdate default sharing groups for resources created by an API key.

Update API Key Scopes

curl --request PATCH \
  --url https://api.example.com/api_keys/{api_key_id} \
  --header 'Content-Type: application/json' \
  --data '
{
  "scopes": [
    {
      "resource_id": "<string>",
      "resource_type": "<string>"
    }
  ]
}
'

{
  "created_by": "<string>",
  "id": "<string>",
  "key_prefix": "<string>",
  "name": "<string>",
  "org_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "last_used_at": "2023-11-07T05:31:56Z",
  "revoked_at": "2023-11-07T05:31:56Z",
  "scopes": [
    {
      "resource_id": "<string>",
      "resource_type": "<string>"
    }
  ],
  "sharing_group_ids": [
    "<string>"
  ]
}

​Valid Roles by Resource Type

Path Parameters

Body

Response

Valid Roles by Resource Type