Orq.ai Documentation - AI Gateway & LLM Collaboration Platform

API Keys

List API Keys

Returns API keys visible to 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.

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)

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"]],
    "permission_mode": List[Literal["PERMISSION_MODE_UNSPECIFIED", "PERMISSION_MODE_ALL", "PERMISSION_MODE_RESTRICTED", "PERMISSION_MODE_READ_ONLY"]],
}

Show Response

{
    "object": str,
    "data": {
        "api_key_id": str,
        "name": str,
        "owner": {
            "user": {  # optional
                "user_id": str,
            },
            "service_account": {},  # optional
        },
        "project_scope": {
            "all": {},  # optional
            "single": {  # optional
                "project_id": str,
            },
        },
        "permission_mode": Literal["PERMISSION_MODE_UNSPECIFIED", "PERMISSION_MODE_ALL", "PERMISSION_MODE_RESTRICTED", "PERMISSION_MODE_READ_ONLY"],
        "access": Dict[str, int],
        "token_prefix": str,
        "status": Literal["API_KEY_STATUS_UNSPECIFIED", "API_KEY_STATUS_ACTIVE", "API_KEY_STATUS_DISABLED", "API_KEY_STATUS_REVOKED"],
        "created_by_id": Optional[str],
        "updated_by_id": Optional[str],
        "created_at": date,
        "updated_at": date,
        "last_used_at": date,
        "expires_at": date,
        "legacy_token_family": Optional[Literal["LEGACY_TOKEN_FAMILY_UNSPECIFIED", "LEGACY_TOKEN_FAMILY_ROUTER_JWT", "LEGACY_TOKEN_FAMILY_PROJECT_JWT", "LEGACY_TOKEN_FAMILY_WORKSPACE_JWT"]],
        "legacy_key_id": Optional[str],
    },
    "has_more": bool,
}

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)

Show Parameters

{
    "name": str,  # required
    "owner": {  # optional
        "user": {  # optional
            "user_id": str,  # required
        },
        "service_account": {},  # optional
    },
    "project_scope": {  # optional
        "all": {},  # 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],
    "expires_at": date,
}

Show Response

{
    "api_key": {
        "api_key_id": str,
        "name": str,
        "owner": {
            "user": {  # optional
                "user_id": str,
            },
            "service_account": {},  # optional
        },
        "project_scope": {
            "all": {},  # optional
            "single": {  # optional
                "project_id": str,
            },
        },
        "permission_mode": Literal["PERMISSION_MODE_UNSPECIFIED", "PERMISSION_MODE_ALL", "PERMISSION_MODE_RESTRICTED", "PERMISSION_MODE_READ_ONLY"],
        "access": Dict[str, int],
        "token_prefix": str,
        "status": Literal["API_KEY_STATUS_UNSPECIFIED", "API_KEY_STATUS_ACTIVE", "API_KEY_STATUS_DISABLED", "API_KEY_STATUS_REVOKED"],
        "created_by_id": Optional[str],
        "updated_by_id": Optional[str],
        "created_at": date,
        "updated_at": date,
        "last_used_at": date,
        "expires_at": date,
        "legacy_token_family": Optional[Literal["LEGACY_TOKEN_FAMILY_UNSPECIFIED", "LEGACY_TOKEN_FAMILY_ROUTER_JWT", "LEGACY_TOKEN_FAMILY_PROJECT_JWT", "LEGACY_TOKEN_FAMILY_WORKSPACE_JWT"]],
        "legacy_key_id": Optional[str],
    },
    "token": str,
}

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)

Show Response

{
    "domains": {
        "id": Optional[str],
        "display_name": Optional[str],
        "group": Optional[int],
        "allowed_scopes": List[int],
        "readable": Optional[bool],
        "writable": Optional[bool],
    },
}

Retrieve an API Key

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.

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)

Show Parameters

{
    "api_key_id": str,  # required
}

Show Response

{
    "api_key": {
        "api_key_id": str,
        "name": str,
        "owner": {
            "user": {  # optional
                "user_id": str,
            },
            "service_account": {},  # optional
        },
        "project_scope": {
            "all": {},  # optional
            "single": {  # optional
                "project_id": str,
            },
        },
        "permission_mode": Literal["PERMISSION_MODE_UNSPECIFIED", "PERMISSION_MODE_ALL", "PERMISSION_MODE_RESTRICTED", "PERMISSION_MODE_READ_ONLY"],
        "access": Dict[str, int],
        "token_prefix": str,
        "status": Literal["API_KEY_STATUS_UNSPECIFIED", "API_KEY_STATUS_ACTIVE", "API_KEY_STATUS_DISABLED", "API_KEY_STATUS_REVOKED"],
        "created_by_id": Optional[str],
        "updated_by_id": Optional[str],
        "created_at": date,
        "updated_at": date,
        "last_used_at": date,
        "expires_at": date,
        "legacy_token_family": Optional[Literal["LEGACY_TOKEN_FAMILY_UNSPECIFIED", "LEGACY_TOKEN_FAMILY_ROUTER_JWT", "LEGACY_TOKEN_FAMILY_PROJECT_JWT", "LEGACY_TOKEN_FAMILY_WORKSPACE_JWT"]],
        "legacy_key_id": Optional[str],
    },
}

Delete an API Key

Permanently deletes an API key. Cache entries in API_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:

    res = orq.api_keys.delete(api_key_id="<id>")

    # Handle response
    print(res)

Show Parameters

{
    "api_key_id": str,  # 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)

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],
    "project_scope": {  # optional
        "all": {},  # optional
        "single": {  # optional
            "project_id": str,  # required
        },
    },
    "expires_at": date,
    "clear_expires_at": Optional[bool],
}

Show Response

{
    "api_key": {
        "api_key_id": str,
        "name": str,
        "owner": {
            "user": {  # optional
                "user_id": str,
            },
            "service_account": {},  # optional
        },
        "project_scope": {
            "all": {},  # optional
            "single": {  # optional
                "project_id": str,
            },
        },
        "permission_mode": Literal["PERMISSION_MODE_UNSPECIFIED", "PERMISSION_MODE_ALL", "PERMISSION_MODE_RESTRICTED", "PERMISSION_MODE_READ_ONLY"],
        "access": Dict[str, int],
        "token_prefix": str,
        "status": Literal["API_KEY_STATUS_UNSPECIFIED", "API_KEY_STATUS_ACTIVE", "API_KEY_STATUS_DISABLED", "API_KEY_STATUS_REVOKED"],
        "created_by_id": Optional[str],
        "updated_by_id": Optional[str],
        "created_at": date,
        "updated_at": date,
        "last_used_at": date,
        "expires_at": date,
        "legacy_token_family": Optional[Literal["LEGACY_TOKEN_FAMILY_UNSPECIFIED", "LEGACY_TOKEN_FAMILY_ROUTER_JWT", "LEGACY_TOKEN_FAMILY_PROJECT_JWT", "LEGACY_TOKEN_FAMILY_WORKSPACE_JWT"]],
        "legacy_key_id": Optional[str],
    },
}

​API Keys

​List API Keys

​Create an API Key

​List Capabilities

​Retrieve an API Key

​Delete an API Key

​Update an API Key

API Keys

List API Keys

Create an API Key

List Capabilities

Retrieve an API Key

Delete an API Key

Update an API Key