Skip to content

README.md

Latest commit

 

History

History
270 lines (179 loc) · 47.5 KB

README.md

File metadata and controls

270 lines (179 loc) · 47.5 KB
Raw

ApiKeys

Overview

Available Operations

list

Returns API keys visible to the current workspace as a JSON array. Raw tokens are never included; the token field contains a masked display value.

Example Usage

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)

Parameters

Parameter Type Required Description
limit Optional[int] ➖ Page size, 1–200. Unset uses the server default (25).
starting_after Optional[str] ➖ Cursor for forward pagination. Set to the api_key_id of the last
item from the previous page.
ending_before Optional[str] ➖ Cursor for backward pagination. Set to the api_key_id of the
first item from the previous page.
project_id Optional[str] ➖ Optional filter: only return keys belonging to this project. When
omitted, returns workspace-scoped and any single-project keys.
status Optional[models.APIKeyStatus] ➖ Optional filter: only return keys with this status.
search Optional[str] ➖ Optional case-insensitive substring match against the api-key
name. Empty means no name filter.
owner_type List[models.OwnerType] ➖ Optional filter: only return keys whose owner.kind matches
one of the requested types. Combines the user / service-account
oneof cases into a single repeated enum so the wire stays flat
and multi-select filters travel as a single field. Empty means
no owner-type filter.
permission_mode List[models.PermissionMode] ➖ Optional filter: only return keys whose permission mode is one
of the listed presets. Empty means no permission-mode filter.
include_budget Optional[bool] ➖ When true, embed each key's api-key-scoped budget (config and limits
only, no live usage) on the returned records. Adds one budget lookup
for the page; omit to skip it.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

List[models.APIKeyRestResponse]

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

create

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.

Example Usage

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)

Parameters

Parameter Type Required Description
name str ✔️ Human-readable name. Required.
owner Optional[models.APIKeyOwner] ➖ Owner attribution. Defaults to service_account when omitted.
project_scope Optional[models.ProjectScope] ➖ Project authorization scope. Defaults to all-projects when omitted.
permission_mode Optional[models.PermissionMode] ➖ N/A
access Dict[str, models.AccessLevel] ➖ Per-domain access map. Required when permission_mode =
PERMISSION_MODE_RESTRICTED. See ApiKey.access for the full
catalog of valid keys (Domain.id) and AccessLevel string values,
or fetch the live catalog via the capability catalog endpoint.
expires_at date ➖ Optional expiration. When set, the authenticate hot-path rejects
the key once expires_at is in the past. Unset means the key
never expires.
mcp_access Optional[models.McpAccess] ➖ Optional MCP-gateway access restriction. Unset means no
restriction. See McpAccess for the deny_all / allow-list semantics.
labels Dict[str, str] ➖ Optional attribution labels (at most 10; keys ^[a-z0-9_.-]{1,32}$,
values up to 64 characters). See ApiKey.labels.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.APIKeyRestResponse

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

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.

Example Usage

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)

Parameters

Parameter Type Required Description
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.ListCapabilitiesResponse

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

get

Retrieves the metadata for an existing API key by its unique identifier. The raw secret is never returned — only token_prefix, permission_mode, project_scope, and lifecycle fields.

Example Usage

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)

Parameters

Parameter Type Required Description
api_key_id str ✔️ API key id to retrieve (e.g. 01H...).
include_budget Optional[bool] ➖ When true, embed the api-key-scoped budget (config and limits only,
no live usage) on the returned record.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.APIKeyRestResponse

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

delete

Permanently deletes an API key. The key is revoked immediately; in-flight requests using it will fail. The response body is empty on success.

Example Usage

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

Parameters

Parameter Type Required Description
api_key_id str ✔️ API key id to delete.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*

update

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.

Example Usage

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)

Parameters

Parameter Type Required Description
api_key_id str ✔️ API key id to update.
name Optional[str] ➖ New name. Omit to keep current.
status Optional[models.APIKeyStatus] ➖ N/A
permission_mode Optional[models.PermissionMode] ➖ N/A
access Dict[str, models.AccessLevel] ➖ Replacement access map. Required when changing to
PERMISSION_MODE_RESTRICTED; ignored otherwise. Provide an empty
map to clear. See ApiKey.access for the full catalog of valid
keys (Domain.id) and AccessLevel string values, or fetch the
live catalog via the capability catalog endpoint.
project_scope Optional[models.ProjectScope] ➖ New project scope. Omit to keep current.
expires_at date ➖ New expiration. Omit to keep current. Set clear_expires_at = true
to remove an existing expiration (a zero Timestamp here would still
mean "no change" because of optional semantics).
clear_expires_at Optional[bool] ➖ Force-clear the expiration. Mutually exclusive with expires_at.
mcp_access Optional[models.McpAccess] ➖ Replacement MCP-gateway access restriction. Absent leaves the
current value intact; an explicitly-set McpAccess replaces it —
including an empty one (deny_all=false + empty list), which clears
any existing restriction. See McpAccess.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.APIKeyRestResponse

Errors

Error Type Status Code Content Type
models.APIDefaultError 4XX, 5XX */*