API REFERENCE
Keys API
Programmatically manage API keys for your organization. Requires the keys:manage permission scope.
The Key Object
Key object
{
"id": "key_abc123def456",
"name": "Production Key",
"prefix": "ya_live_sk_abc1",
"environment": "live",
"scopes": ["agents:read", "agents:write", "agents:execute"],
"lastUsed": "2026-03-15T10:30:00Z",
"expiresAt": null,
"createdAt": "2026-03-01T00:00:00Z"
}
Note
The full key value is only returned once at creation time. After that, only the prefix (first 16 characters) is available for identification.
Create a Key
POST /v1/keys
Request
{
"name": "Production Key",
"environment": "live",
"scopes": ["agents:read", "agents:write", "agents:execute"],
"expiresAt": "2027-03-15T00:00:00Z"
}
Response (201)
{
"id": "key_abc123def456",
"name": "Production Key",
"key": "ya_live_sk_abc123def456ghi789...",
"prefix": "ya_live_sk_abc1",
"environment": "live",
"scopes": ["agents:read", "agents:write", "agents:execute"],
"expiresAt": "2027-03-15T00:00:00Z",
"createdAt": "2026-03-15T10:30:00Z"
}
List Keys
GET /v1/keys
Response (200)
{
"data": [
{
"id": "key_abc123",
"name": "Production Key",
"prefix": "ya_live_sk_abc1",
"environment": "live",
"scopes": ["agents:read", "agents:write", "agents:execute"],
"lastUsed": "2026-03-15T10:30:00Z",
"createdAt": "2026-03-01T00:00:00Z"
}
],
"hasMore": false
}
Revoke a Key
DELETE /v1/keys/:id
Immediately revokes the key. Any requests using this key will receive a 401 Unauthorized response. This action cannot be undone.
Response (200)
{
"id": "key_abc123def456",
"deleted": true,
"revokedAt": "2026-03-15T10:30:00Z"
}
Key Rotation
To rotate a key safely without downtime:
- 1.Create a new key with the same scopes
- 2.Update your application to use the new key
- 3.Verify the new key works in production
- 4.Revoke the old key