Update a child API key | Saperly Docs

const url = 'https://saperly.com/api/v1/keys/id';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{}'
};
try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

{
  "key": {
    "id": "string",
    "key_prefix": "sk_live_abc",
    "environment": "live",
    "name": "string",
    "agent_label": "string",
    "line_id": "string",
    "permissions": "full",
    "monthly_cap_cents": 1,
    "monthly_spend_cents": 1,
    "created_at": "2024-01-15T09:30:00Z",
    "revoked_at": "2024-01-15T09:30:00Z",
    "last_used_at": "2024-01-15T09:30:00Z",
    "rotated_from": "string",
    "created_by_service_key_id": "string"
  }
}

Updates a child API key. All fields are optional; at least one must be provided. `line_id=null` unbinds the key (wildcard / account-wide); a non-null `line_id` must point to a non-released line owned by the same user in the same environment, otherwise a 422 validation error is returned for the env mismatch and a 404 for missing/released lines. `permissions` accepts the four customer-settable tiers (`full`, `call_only`, `sms_only`, `read_only`). The backfill-only `legacy_full` tier cannot be set via the API.

const url = 'https://saperly.com/api/v1/keys/id';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{}'
};
try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

{
  "key": {
    "id": "string",
    "key_prefix": "sk_live_abc",
    "environment": "live",
    "name": "string",
    "agent_label": "string",
    "line_id": "string",
    "permissions": "full",
    "monthly_cap_cents": 1,
    "monthly_spend_cents": 1,
    "created_at": "2024-01-15T09:30:00Z",
    "revoked_at": "2024-01-15T09:30:00Z",
    "last_used_at": "2024-01-15T09:30:00Z",
    "rotated_from": "string",
    "created_by_service_key_id": "string"
  }
}

Updates a child API key. All fields are optional; at least one must be provided. line_id=null unbinds the key (wildcard / account-wide); a non-null line_id must point to a non-released line owned by the same user in the same environment, otherwise a 422 validation error is returned for the env mismatch and a 404 for missing/released lines.

permissions accepts the four customer-settable tiers (full, call_only, sms_only, read_only). The backfill-only legacy_full tier cannot be set via the API.

Authentication

AuthorizationBearer

Service keys (sk_svc_*) authenticate the /v1/keys/* management plane. Send as Authorization: Bearer <service-key>. Service keys are minted only from the portal (Settings → Service Keys); there is no API path to mint another service key.

Path parameters

idstringRequiredformat: "uuid"

Child API key ID

Request

This endpoint expects an object.

namestringOptional1-64 characters

agent_labelstring or nullOptionalformat: "^[a-z0-9][a-z0-9:_.-]{0,127}$"

line_idstring or nullOptionalformat: "uuid"

permissionsenumOptional

Allowed values:

monthly_cap_centsinteger or nullOptional1-1000000

Response

Child API key updated

keyobject

A child API key (sk_test_* / sk_live_*). Minted via the portal (UI) or programmatically via POST /v1/keys when authenticated as a service key.

Errors

401

Unauthorized Error

404

Not Found Error

422

Unprocessable Entity Error

1	const url = 'https://saperly.com/api/v1/keys/id';
2	const options = {
3	method: 'PATCH',
4	headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
5	body: '{}'
6	};
7
8	try {
9	const response = await fetch(url, options);
10	const data = await response.json();
11	console.log(data);
12	} catch (error) {
13	console.error(error);
14	}

1	{
2	"key": {
3	"id": "string",
4	"key_prefix": "sk_live_abc",
5	"environment": "live",
6	"name": "string",
7	"agent_label": "string",
8	"line_id": "string",
9	"permissions": "full",
10	"monthly_cap_cents": 1,
11	"monthly_spend_cents": 1,
12	"created_at": "2024-01-15T09:30:00Z",
13	"revoked_at": "2024-01-15T09:30:00Z",
14	"last_used_at": "2024-01-15T09:30:00Z",
15	"rotated_from": "string",
16	"created_by_service_key_id": "string"
17	}
18	}