Management Keys SDK Reference - Orq.ai Documentation

Management Keys

List Management Keys

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.

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)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.managementKeys.list();

  console.log(result);
}

run();

Show Parameters

{
    "limit": Optional[int],
    "starting_after": Optional[str],
    "ending_before": Optional[str],
    "status": Optional[Literal["MANAGEMENT_KEY_STATUS_UNSPECIFIED", "MANAGEMENT_KEY_STATUS_ACTIVE", "MANAGEMENT_KEY_STATUS_DISABLED", "MANAGEMENT_KEY_STATUS_REVOKED"]],
    "search": Optional[str],
    "permission_mode": List[Literal["MANAGEMENT_PERMISSION_MODE_UNSPECIFIED", "MANAGEMENT_PERMISSION_MODE_ALL", "MANAGEMENT_PERMISSION_MODE_RESTRICTED", "MANAGEMENT_PERMISSION_MODE_READ_ONLY"]],
}

{
  limit?: number;
  startingAfter?: string;
  endingBefore?: string;
  status?: string;
  search?: string;
  permissionMode?: string;
}

Show Response

{
    "object": str,
    "data": {
        "management_key_id": str,
        "name": str,
        "permission_mode": Literal["MANAGEMENT_PERMISSION_MODE_UNSPECIFIED", "MANAGEMENT_PERMISSION_MODE_ALL", "MANAGEMENT_PERMISSION_MODE_RESTRICTED", "MANAGEMENT_PERMISSION_MODE_READ_ONLY"],
        "access": Dict[str, int],
        "token_prefix": str,
        "status": Literal["MANAGEMENT_KEY_STATUS_UNSPECIFIED", "MANAGEMENT_KEY_STATUS_ACTIVE", "MANAGEMENT_KEY_STATUS_DISABLED", "MANAGEMENT_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,
    },
    "has_more": bool,
}

{
  object: string;
  data: {
    managementKeyId: string;
    name: string;
    permissionMode: string;
    access?: Record<string, number>;
    tokenPrefix: string;
    status: string;
    createdById?: string;
    updatedById?: string;
    createdAt: Date;
    updatedAt: Date;
    lastUsedAt?: Date;
    expiresAt?: Date;
  };
  hasMore: boolean;
}

Create a Management Key

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.

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)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.managementKeys.create({
    name: "<value>",
  });

  console.log(result);
}

run();

Show Parameters

{
    "name": str,  # required
    "permission_mode": Optional[Literal["MANAGEMENT_PERMISSION_MODE_UNSPECIFIED", "MANAGEMENT_PERMISSION_MODE_ALL", "MANAGEMENT_PERMISSION_MODE_RESTRICTED", "MANAGEMENT_PERMISSION_MODE_READ_ONLY"]],
    "access": Dict[str, int],
    "expires_at": date,
}

{
  name: string;  // required
  permissionMode?: string;
  access?: Record<string, number>;
  expiresAt?: Date;
}

Show Response

{
    "management_key": {
        "management_key_id": str,
        "name": str,
        "permission_mode": Literal["MANAGEMENT_PERMISSION_MODE_UNSPECIFIED", "MANAGEMENT_PERMISSION_MODE_ALL", "MANAGEMENT_PERMISSION_MODE_RESTRICTED", "MANAGEMENT_PERMISSION_MODE_READ_ONLY"],
        "access": Dict[str, int],
        "token_prefix": str,
        "status": Literal["MANAGEMENT_KEY_STATUS_UNSPECIFIED", "MANAGEMENT_KEY_STATUS_ACTIVE", "MANAGEMENT_KEY_STATUS_DISABLED", "MANAGEMENT_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,
    },
    "token": str,
}

{
  managementKey: {
    managementKeyId: string;
    name: string;
    permissionMode: string;
    access?: Record<string, number>;
    tokenPrefix: string;
    status: string;
    createdById?: string;
    updatedById?: string;
    createdAt: Date;
    updatedAt: Date;
    lastUsedAt?: Date;
    expiresAt?: Date;
  };
  token: string;
}

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.

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)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.managementKeys.listCapabilities();

  console.log(result);
}

run();

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 a Management Key

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.

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)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.managementKeys.get({
    managementKeyId: "<id>",
  });

  console.log(result);
}

run();

Show Parameters

{
    "management_key_id": str,  # required
}

{
  managementKeyId: string;  // required
}

Show Response

{
    "management_key": {
        "management_key_id": str,
        "name": str,
        "permission_mode": Literal["MANAGEMENT_PERMISSION_MODE_UNSPECIFIED", "MANAGEMENT_PERMISSION_MODE_ALL", "MANAGEMENT_PERMISSION_MODE_RESTRICTED", "MANAGEMENT_PERMISSION_MODE_READ_ONLY"],
        "access": Dict[str, int],
        "token_prefix": str,
        "status": Literal["MANAGEMENT_KEY_STATUS_UNSPECIFIED", "MANAGEMENT_KEY_STATUS_ACTIVE", "MANAGEMENT_KEY_STATUS_DISABLED", "MANAGEMENT_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,
    },
}

{
  managementKey: {
    managementKeyId: string;
    name: string;
    permissionMode: string;
    access?: Record<string, number>;
    tokenPrefix: string;
    status: string;
    createdById?: string;
    updatedById?: string;
    createdAt: Date;
    updatedAt: Date;
    lastUsedAt?: Date;
    expiresAt?: Date;
  };
}

Delete a Management Key

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.

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)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.managementKeys.delete({
    managementKeyId: "<id>",
  });

  console.log(result);
}

run();

Show Parameters

{
    "management_key_id": str,  # required
}

{
  managementKeyId: string;  // required
}

Update a Management Key

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.

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)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.managementKeys.update({
    managementKeyId: "<id>",
    updateManagementKeyRequest: {},
  });

  console.log(result);
}

run();

Show Parameters

{
    "management_key_id": str,  # required
    "name": Optional[str],
    "status": Optional[Literal["MANAGEMENT_KEY_STATUS_UNSPECIFIED", "MANAGEMENT_KEY_STATUS_ACTIVE", "MANAGEMENT_KEY_STATUS_DISABLED", "MANAGEMENT_KEY_STATUS_REVOKED"]],
    "permission_mode": Optional[Literal["MANAGEMENT_PERMISSION_MODE_UNSPECIFIED", "MANAGEMENT_PERMISSION_MODE_ALL", "MANAGEMENT_PERMISSION_MODE_RESTRICTED", "MANAGEMENT_PERMISSION_MODE_READ_ONLY"]],
    "access": Dict[str, int],
    "expires_at": date,
    "clear_expires_at": Optional[bool],
}

{
  managementKeyId: string;  // required
  updateManagementKeyRequest: {  // required
    name?: string;
    status?: string;
    permissionMode?: string;
    access?: Record<string, number>;
    expiresAt?: Date;
    clearExpiresAt?: boolean;
  };
}

Show Response

{
    "management_key": {
        "management_key_id": str,
        "name": str,
        "permission_mode": Literal["MANAGEMENT_PERMISSION_MODE_UNSPECIFIED", "MANAGEMENT_PERMISSION_MODE_ALL", "MANAGEMENT_PERMISSION_MODE_RESTRICTED", "MANAGEMENT_PERMISSION_MODE_READ_ONLY"],
        "access": Dict[str, int],
        "token_prefix": str,
        "status": Literal["MANAGEMENT_KEY_STATUS_UNSPECIFIED", "MANAGEMENT_KEY_STATUS_ACTIVE", "MANAGEMENT_KEY_STATUS_DISABLED", "MANAGEMENT_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,
    },
}

{
  managementKey: {
    managementKeyId: string;
    name: string;
    permissionMode: string;
    access?: Record<string, number>;
    tokenPrefix: string;
    status: string;
    createdById?: string;
    updatedById?: string;
    createdAt: Date;
    updatedAt: Date;
    lastUsedAt?: Date;
    expiresAt?: Date;
  };
}

​Management Keys

​List Management Keys

​Create a Management Key

​List Capabilities

​Retrieve a Management Key

​Delete a Management Key

​Update a Management Key

Management Keys

List Management Keys

Create a Management Key

List Capabilities

Retrieve a Management Key

Delete a Management Key

Update a Management Key