Skip to content

README.md

Latest commit

 

History

History
265 lines (172 loc) · 26.4 KB

README.md

File metadata and controls

265 lines (172 loc) · 26.4 KB
Raw

ManagementKeys

Overview

Available Operations

  • list - List management keys
  • create - Create a new management key
  • list_capabilities - List management capability catalog
  • get - Retrieve a management key
  • delete - Delete a management key
  • update - Update a management key

list

Returns management keys in the current workspace, ordered by creation time with the newest key first. The api_key and token_hash fields are never returned by this endpoint; only token_prefix is included.

Example Usage

from orq_ai_sdk import Orq
import os


with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.management_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 management_key_id of the
last item from the previous page.
ending_before Optional[str] ➖ Cursor for backward pagination. Set to the management_key_id of the
first item from the previous page.
status Optional[models.ManagementKeyStatus] ➖ Optional filter: only return keys with this status.
search Optional[str] ➖ Optional case-insensitive substring match against the management-key
name. Empty means no name filter.
permission_mode List[models.ManagementPermissionMode] ➖ Optional filter: only return keys whose permission mode is one of
the listed presets. Empty means no permission-mode filter.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.ListManagementKeysResponse

Errors

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

create

Mints a new opaque management 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.management_keys.create(name="<value>")

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
name str ✔️ Human-readable name. Required.
permission_mode Optional[models.ManagementPermissionMode] ➖ N/A
access Dict[str, models.AccessLevel] ➖ Per-domain access map. Required when permission_mode =
MANAGEMENT_PERMISSION_MODE_RESTRICTED. See ManagementKey.access
for the 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.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.CreateManagementKeyResponse

Errors

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

list_capabilities

Returns the management capability catalog: the set of workspace-admin permission domains that can be granted to a management key. Each entry includes the domain id, display name, group, and the read / write verb support. 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.management_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.ListManagementCapabilitiesResponse

Errors

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

get

Retrieves the metadata for an existing management key by its unique identifier. The raw secret is never returned — only token_prefix, permission_mode, 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.management_keys.get(management_key_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
management_key_id str ✔️ Management key id to retrieve (e.g. 01H...).
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.GetManagementKeyResponse

Errors

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

delete

Permanently deletes a management key. Cache entries are invalidated immediately so an in-flight token cannot ride out the TTL. 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:

    res = orq.management_keys.delete(management_key_id="<id>")

    # Handle response
    print(res)

Parameters

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

Response

models.DeleteManagementKeyResponse

Errors

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

update

Updates mutable fields of a management key: display name, status (active / disabled / revoked), permission mode and access map, and 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.management_keys.update(management_key_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
management_key_id str ✔️ Management key id to update.
name Optional[str] ➖ New name. Omit to keep current.
status Optional[models.ManagementKeyStatus] ➖ N/A
permission_mode Optional[models.ManagementPermissionMode] ➖ N/A
access Dict[str, models.AccessLevel] ➖ Replacement access map. Required when changing to
MANAGEMENT_PERMISSION_MODE_RESTRICTED; ignored otherwise. Provide
an empty map to clear.
expires_at date ➖ New expiration. Omit to keep current. Set clear_expires_at = true
to remove an existing expiration.
clear_expires_at Optional[bool] ➖ Force-clear the expiration. Mutually exclusive with expires_at.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.UpdateManagementKeyResponse

Errors

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