API Keys
List API Keys
Returns API keys visible to the current workspace as a JSON array. Raw tokens are never included; thetoken field contains a masked display value.
from orq_ai_sdk import Orq
import os
with Orq(
api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:
res = orq.api_keys.list()
# Handle response
print(res)
import { Orq } from "@orq-ai/node";
const orq = new Orq({
apiKey: process.env["ORQ_API_KEY"] ?? "",
});
async function run() {
const result = await orq.apiKeys.list();
console.log(result);
}
run();
Show Parameters
Show Parameters
{
"limit": Optional[int],
"starting_after": Optional[str],
"ending_before": Optional[str],
"project_id": Optional[str],
"status": Optional[Literal["API_KEY_STATUS_UNSPECIFIED", "API_KEY_STATUS_ACTIVE", "API_KEY_STATUS_DISABLED", "API_KEY_STATUS_REVOKED"]],
"search": Optional[str],
"owner_type": List[Literal["OWNER_TYPE_UNSPECIFIED", "OWNER_TYPE_USER", "OWNER_TYPE_SERVICE_ACCOUNT"]], # optional
"permission_mode": List[Literal["PERMISSION_MODE_UNSPECIFIED", "PERMISSION_MODE_ALL", "PERMISSION_MODE_RESTRICTED", "PERMISSION_MODE_READ_ONLY"]], # optional
"include_budget": Optional[bool],
}
{
limit?: number;
startingAfter?: string;
endingBefore?: string;
projectId?: string;
status?: "API_KEY_STATUS_UNSPECIFIED" | "API_KEY_STATUS_ACTIVE" | "API_KEY_STATUS_DISABLED" | "API_KEY_STATUS_REVOKED";
search?: string;
ownerType?: ("OWNER_TYPE_UNSPECIFIED" | "OWNER_TYPE_USER" | "OWNER_TYPE_SERVICE_ACCOUNT")[];
permissionMode?: ("PERMISSION_MODE_UNSPECIFIED" | "PERMISSION_MODE_ALL" | "PERMISSION_MODE_RESTRICTED" | "PERMISSION_MODE_READ_ONLY")[];
includeBudget?: boolean;
}
Create an API Key
Mints a new opaque API key (sk-orq-<key_id>-<secret>) in the workspace. The raw secret is returned ONCE in the response and is never retrievable afterwards. The stored record retains only token_prefix and a SHA-256 token_hash.
from orq_ai_sdk import Orq
import os
with Orq(
api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:
res = orq.api_keys.create(name="<value>")
# Handle response
print(res)
import { Orq } from "@orq-ai/node";
const orq = new Orq({
apiKey: process.env["ORQ_API_KEY"] ?? "",
});
async function run() {
const result = await orq.apiKeys.create({
name: "<value>",
});
console.log(result);
}
run();
Show Parameters
Show Parameters
{
"name": str, # required
"owner": { # optional
"user": { # optional
"user_id": str, # required
},
"service_account": Dict[str, Any], # optional
},
"project_scope": { # optional
"all": Dict[str, Any], # optional
"single": { # optional
"project_id": str, # required
},
},
"permission_mode": Optional[Literal["PERMISSION_MODE_UNSPECIFIED", "PERMISSION_MODE_ALL", "PERMISSION_MODE_RESTRICTED", "PERMISSION_MODE_READ_ONLY"]],
"access": Dict[str, int], # optional
"expires_at": date, # optional
"mcp_access": { # optional
"deny_all": Optional[bool],
"allowed_mcp_gateway_ids": List[str], # optional
"toolset_ids": List[str], # optional
},
}
{
name: string; // required
owner?: {
user?: {
userId: string; // required
};
serviceAccount?: Record<string, unknown>;
};
projectScope?: {
all?: Record<string, unknown>;
single?: {
projectId: string; // required
};
};
permissionMode?: "PERMISSION_MODE_UNSPECIFIED" | "PERMISSION_MODE_ALL" | "PERMISSION_MODE_RESTRICTED" | "PERMISSION_MODE_READ_ONLY";
access?: Record<string, number>;
expiresAt?: Date;
mcpAccess?: {
denyAll?: boolean;
allowedMcpGatewayIds?: string[];
toolsetIds?: string[];
};
}
Show Response
Show Response
{
"id": str,
"name": str,
"workspace_id": str,
"token": str,
"active": Optional[bool],
"is_legacy": Optional[bool],
"source": Optional[str],
"budget": Dict[str, Any], # optional
"expiration": date, # optional
"projects": List[str], # optional
"created_by_id": Optional[str],
"updated_by_id": Optional[str],
"created": date, # optional
"updated": date, # optional
"consumption": Optional[float],
"token_consumption": Optional[float],
"requests_per_minute_consumption": Optional[float],
"owner": Dict[str, Any], # optional
"project_scope": Dict[str, Any], # optional
"permission_mode": Optional[str],
"access": Dict[str, str], # optional
"token_prefix": Optional[str],
"status": Optional[str],
"constraints": Dict[str, Any], # optional
"mcp_access": Dict[str, Any], # optional
"legacy_token_family": Optional[str],
"legacy_key_id": Optional[str],
"last_used_at": date, # optional
}
{
id: string;
name: string;
workspaceId: string;
token: string;
active?: boolean;
isLegacy?: boolean;
source?: string;
budget?: Record<string, any>;
expiration?: Date;
projects?: string[];
createdById?: string;
updatedById?: string;
created?: Date;
updated?: Date;
consumption?: number;
tokenConsumption?: number;
requestsPerMinuteConsumption?: number;
owner?: Record<string, any>;
projectScope?: Record<string, any>;
permissionMode?: string;
access?: Record<string, string>;
tokenPrefix?: string;
status?: string;
constraints?: Record<string, any>;
mcpAccess?: Record<string, any>;
legacyTokenFamily?: string;
legacyKeyId?: string;
lastUsedAt?: Date;
}
List Capabilities
Returns the capability catalog: the set of permission domains that can be granted to an API key. Each entry includes the domain id, display name, group, allowed project scopes, and the read / write verb sets resolved at authorize() time. Drives the permissions UI in the dashboard.from orq_ai_sdk import Orq
import os
with Orq(
api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:
res = orq.api_keys.list_capabilities()
# Handle response
print(res)
import { Orq } from "@orq-ai/node";
const orq = new Orq({
apiKey: process.env["ORQ_API_KEY"] ?? "",
});
async function run() {
const result = await orq.apiKeys.listCapabilities();
console.log(result);
}
run();
Show Response
Show Response
{
"domains": [{
"id": Optional[str],
"display_name": Optional[str],
"group": Optional[int],
"readable": Optional[bool],
"writable": Optional[bool],
}],
}
{
domains: {
id?: string;
displayName?: string;
group?: number;
readable?: boolean;
writable?: boolean;
}[];
}
Retrieve an API Key
Retrieves the metadata for an existing API key by its unique identifier. The raw secret is never returned: onlytoken_prefix, permission_mode, project_scope, and lifecycle fields.
from orq_ai_sdk import Orq
import os
with Orq(
api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:
res = orq.api_keys.get(api_key_id="<id>")
# Handle response
print(res)
import { Orq } from "@orq-ai/node";
const orq = new Orq({
apiKey: process.env["ORQ_API_KEY"] ?? "",
});
async function run() {
const result = await orq.apiKeys.get({
apiKeyId: "<id>",
});
console.log(result);
}
run();
Show Parameters
Show Parameters
{
"api_key_id": str, # required
"include_budget": Optional[bool],
}
{
apiKeyId: string; // required
includeBudget?: boolean;
}
Show Response
Show Response
{
"id": str,
"name": str,
"workspace_id": str,
"token": str,
"active": Optional[bool],
"is_legacy": Optional[bool],
"source": Optional[str],
"budget": Dict[str, Any], # optional
"expiration": date, # optional
"projects": List[str], # optional
"created_by_id": Optional[str],
"updated_by_id": Optional[str],
"created": date, # optional
"updated": date, # optional
"consumption": Optional[float],
"token_consumption": Optional[float],
"requests_per_minute_consumption": Optional[float],
"owner": Dict[str, Any], # optional
"project_scope": Dict[str, Any], # optional
"permission_mode": Optional[str],
"access": Dict[str, str], # optional
"token_prefix": Optional[str],
"status": Optional[str],
"constraints": Dict[str, Any], # optional
"mcp_access": Dict[str, Any], # optional
"legacy_token_family": Optional[str],
"legacy_key_id": Optional[str],
"last_used_at": date, # optional
}
{
id: string;
name: string;
workspaceId: string;
token: string;
active?: boolean;
isLegacy?: boolean;
source?: string;
budget?: Record<string, any>;
expiration?: Date;
projects?: string[];
createdById?: string;
updatedById?: string;
created?: Date;
updated?: Date;
consumption?: number;
tokenConsumption?: number;
requestsPerMinuteConsumption?: number;
owner?: Record<string, any>;
projectScope?: Record<string, any>;
permissionMode?: string;
access?: Record<string, string>;
tokenPrefix?: string;
status?: string;
constraints?: Record<string, any>;
mcpAccess?: Record<string, any>;
legacyTokenFamily?: string;
legacyKeyId?: string;
lastUsedAt?: Date;
}
Delete an API Key
Permanently deletes an API key. Cache entries inAPI_KEYS_KV are invalidated immediately so an in-flight token cannot ride out the TTL. The response body is empty on success.
from orq_ai_sdk import Orq
import os
with Orq(
api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:
orq.api_keys.delete(api_key_id="<id>")
# Use the SDK ...
import { Orq } from "@orq-ai/node";
const orq = new Orq({
apiKey: process.env["ORQ_API_KEY"] ?? "",
});
async function run() {
await orq.apiKeys.delete({
apiKeyId: "<id>",
});
}
run();
Show Parameters
Show Parameters
{
"api_key_id": str, # required
}
{
apiKeyId: string; // required
}
Update an API Key
Updates mutable fields of an API key: display name, status (active / disabled / revoked), permission mode and access map, project scope, and constraints (budget / rate limit / expiry). Omitted fields keep their current values.from orq_ai_sdk import Orq
import os
with Orq(
api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:
res = orq.api_keys.update(api_key_id="<value>")
# Handle response
print(res)
import { Orq } from "@orq-ai/node";
const orq = new Orq({
apiKey: process.env["ORQ_API_KEY"] ?? "",
});
async function run() {
const result = await orq.apiKeys.update({
apiKeyId: "<id>",
updateApiKeyRequest: {},
});
console.log(result);
}
run();
Show Parameters
Show Parameters
{
"api_key_id": str, # required
"name": Optional[str],
"status": Optional[Literal["API_KEY_STATUS_UNSPECIFIED", "API_KEY_STATUS_ACTIVE", "API_KEY_STATUS_DISABLED", "API_KEY_STATUS_REVOKED"]],
"permission_mode": Optional[Literal["PERMISSION_MODE_UNSPECIFIED", "PERMISSION_MODE_ALL", "PERMISSION_MODE_RESTRICTED", "PERMISSION_MODE_READ_ONLY"]],
"access": Dict[str, int], # optional
"project_scope": { # optional
"all": Dict[str, Any], # optional
"single": { # optional
"project_id": str, # required
},
},
"expires_at": date, # optional
"clear_expires_at": Optional[bool],
"mcp_access": { # optional
"deny_all": Optional[bool],
"allowed_mcp_gateway_ids": List[str], # optional
"toolset_ids": List[str], # optional
},
}
{
apiKeyId: string; // required
updateApiKeyRequest: { // required
name?: string;
status?: "API_KEY_STATUS_UNSPECIFIED" | "API_KEY_STATUS_ACTIVE" | "API_KEY_STATUS_DISABLED" | "API_KEY_STATUS_REVOKED";
permissionMode?: "PERMISSION_MODE_UNSPECIFIED" | "PERMISSION_MODE_ALL" | "PERMISSION_MODE_RESTRICTED" | "PERMISSION_MODE_READ_ONLY";
access?: Record<string, number>;
projectScope?: {
all?: Record<string, unknown>;
single?: {
projectId: string; // required
};
};
expiresAt?: Date;
clearExpiresAt?: boolean;
mcpAccess?: {
denyAll?: boolean;
allowedMcpGatewayIds?: string[];
toolsetIds?: string[];
};
};
}
Show Response
Show Response
{
"id": str,
"name": str,
"workspace_id": str,
"token": str,
"active": Optional[bool],
"is_legacy": Optional[bool],
"source": Optional[str],
"budget": Dict[str, Any], # optional
"expiration": date, # optional
"projects": List[str], # optional
"created_by_id": Optional[str],
"updated_by_id": Optional[str],
"created": date, # optional
"updated": date, # optional
"consumption": Optional[float],
"token_consumption": Optional[float],
"requests_per_minute_consumption": Optional[float],
"owner": Dict[str, Any], # optional
"project_scope": Dict[str, Any], # optional
"permission_mode": Optional[str],
"access": Dict[str, str], # optional
"token_prefix": Optional[str],
"status": Optional[str],
"constraints": Dict[str, Any], # optional
"mcp_access": Dict[str, Any], # optional
"legacy_token_family": Optional[str],
"legacy_key_id": Optional[str],
"last_used_at": date, # optional
}
{
id: string;
name: string;
workspaceId: string;
token: string;
active?: boolean;
isLegacy?: boolean;
source?: string;
budget?: Record<string, any>;
expiration?: Date;
projects?: string[];
createdById?: string;
updatedById?: string;
created?: Date;
updated?: Date;
consumption?: number;
tokenConsumption?: number;
requestsPerMinuteConsumption?: number;
owner?: Record<string, any>;
projectScope?: Record<string, any>;
permissionMode?: string;
access?: Record<string, string>;
tokenPrefix?: string;
status?: string;
constraints?: Record<string, any>;
mcpAccess?: Record<string, any>;
legacyTokenFamily?: string;
legacyKeyId?: string;
lastUsedAt?: Date;
}