Skip to main content
PATCH
/
api_keys
/
{api_key_id}
/
sharing-groups
Update API Key Sharing Groups
curl --request PATCH \
  --url https://api.example.com/api_keys/{api_key_id}/sharing-groups \
  --header 'Content-Type: application/json' \
  --data '
{
  "sharing_group_ids": [
    "<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>"
  ]
}
When an API key creates a resource (agent or project), sharing groups automatically receive owner access to that resource. How it works:
  1. Key creation - The key’s service user is added as a member to each sharing group
  2. Resource creation - When the key creates an agent/project, each sharing group gets owner role
  3. Effect - All members of the sharing groups automatically get owner access
A key with no sharing groups can create resources that only it can access. Always assign at least one sharing group for team visibility.

Path Parameters

​
api_key_id
string
required

Body

application/json

Request model for updating API key sharing groups.

​
sharing_group_ids
string[]
required

Replacement sharing groups (future creations only).

Minimum array length: 1

Response

Successful Response

Response model for API key (excludes sensitive data).

​
created_by
string
required

member_id of the creator.

​
id
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.

​
sharing_group_ids
string[]

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