> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Management Keys SDK Reference

> Manage management keys with the Node.js and Python SDKs: create, list, update, and delete workspace admin keys and list their capabilities.

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

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "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"]],  # optional
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      limit?: number;
      startingAfter?: string;
      endingBefore?: string;
      status?: "MANAGEMENT_KEY_STATUS_UNSPECIFIED" | "MANAGEMENT_KEY_STATUS_ACTIVE" | "MANAGEMENT_KEY_STATUS_DISABLED" | "MANAGEMENT_KEY_STATUS_REVOKED";
      search?: string;
      permissionMode?: ("MANAGEMENT_PERMISSION_MODE_UNSPECIFIED" | "MANAGEMENT_PERMISSION_MODE_ALL" | "MANAGEMENT_PERMISSION_MODE_RESTRICTED" | "MANAGEMENT_PERMISSION_MODE_READ_ONLY")[];
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "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, AccessLevel],  # optional
            "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": str,
            "updated_at": str,
            "last_used_at": str,  # optional
            "expires_at": str,  # optional
        }],
        "has_more": bool,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      object: string;
      data: {
        managementKeyId: string;
        name: string;
        permissionMode: "MANAGEMENT_PERMISSION_MODE_UNSPECIFIED" | "MANAGEMENT_PERMISSION_MODE_ALL" | "MANAGEMENT_PERMISSION_MODE_RESTRICTED" | "MANAGEMENT_PERMISSION_MODE_READ_ONLY";
        access?: string;
        tokenPrefix: string;
        status: "MANAGEMENT_KEY_STATUS_UNSPECIFIED" | "MANAGEMENT_KEY_STATUS_ACTIVE" | "MANAGEMENT_KEY_STATUS_DISABLED" | "MANAGEMENT_KEY_STATUS_REVOKED";
        createdById?: string;
        updatedById?: string;
        createdAt: Date;
        updatedAt: Date;
        lastUsedAt?: Date;
        expiresAt?: Date;
      }[];
      hasMore: boolean;
    }
    ```
  </CodeGroup>
</Expandable>

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

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "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, AccessLevel],  # optional
        "expires_at": str,  # optional
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      name: string;  // required
      permissionMode?: "MANAGEMENT_PERMISSION_MODE_UNSPECIFIED" | "MANAGEMENT_PERMISSION_MODE_ALL" | "MANAGEMENT_PERMISSION_MODE_RESTRICTED" | "MANAGEMENT_PERMISSION_MODE_READ_ONLY";
      access?: string;
      expiresAt?: Date;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "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, AccessLevel],  # optional
            "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": str,
            "updated_at": str,
            "last_used_at": str,  # optional
            "expires_at": str,  # optional
        },
        "token": str,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      managementKey: {
        managementKeyId: string;
        name: string;
        permissionMode: "MANAGEMENT_PERMISSION_MODE_UNSPECIFIED" | "MANAGEMENT_PERMISSION_MODE_ALL" | "MANAGEMENT_PERMISSION_MODE_RESTRICTED" | "MANAGEMENT_PERMISSION_MODE_READ_ONLY";
        access?: string;
        tokenPrefix: string;
        status: "MANAGEMENT_KEY_STATUS_UNSPECIFIED" | "MANAGEMENT_KEY_STATUS_ACTIVE" | "MANAGEMENT_KEY_STATUS_DISABLED" | "MANAGEMENT_KEY_STATUS_REVOKED";
        createdById?: string;
        updatedById?: string;
        createdAt: Date;
        updatedAt: Date;
        lastUsedAt?: Date;
        expiresAt?: Date;
      };
      token: string;
    }
    ```
  </CodeGroup>
</Expandable>

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

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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();
  ```
</CodeGroup>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "domains": [{
            "id": Optional[str],
            "display_name": Optional[str],
            "group": Optional[Literal["DOMAIN_GROUP_WORKSPACE_ADMIN"]],
            "readable": Optional[bool],
            "writable": Optional[bool],
        }],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      domains: {
        id?: string;
        displayName?: string;
        group?: "DOMAIN_GROUP_WORKSPACE_ADMIN";
        readable?: boolean;
        writable?: boolean;
      }[];
    }
    ```
  </CodeGroup>
</Expandable>

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

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "management_key_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      managementKeyId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "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, AccessLevel],  # optional
            "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": str,
            "updated_at": str,
            "last_used_at": str,  # optional
            "expires_at": str,  # optional
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      managementKey: {
        managementKeyId: string;
        name: string;
        permissionMode: "MANAGEMENT_PERMISSION_MODE_UNSPECIFIED" | "MANAGEMENT_PERMISSION_MODE_ALL" | "MANAGEMENT_PERMISSION_MODE_RESTRICTED" | "MANAGEMENT_PERMISSION_MODE_READ_ONLY";
        access?: string;
        tokenPrefix: string;
        status: "MANAGEMENT_KEY_STATUS_UNSPECIFIED" | "MANAGEMENT_KEY_STATUS_ACTIVE" | "MANAGEMENT_KEY_STATUS_DISABLED" | "MANAGEMENT_KEY_STATUS_REVOKED";
        createdById?: string;
        updatedById?: string;
        createdAt: Date;
        updatedAt: Date;
        lastUsedAt?: Date;
        expiresAt?: Date;
      };
    }
    ```
  </CodeGroup>
</Expandable>

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

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "management_key_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      managementKeyId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

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

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "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, AccessLevel],  # optional
        "expires_at": str,  # optional
        "clear_expires_at": Optional[bool],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      managementKeyId: string;  // required
      updateManagementKeyRequest: {  // required
        name?: string;
        status?: "MANAGEMENT_KEY_STATUS_UNSPECIFIED" | "MANAGEMENT_KEY_STATUS_ACTIVE" | "MANAGEMENT_KEY_STATUS_DISABLED" | "MANAGEMENT_KEY_STATUS_REVOKED";
        permissionMode?: "MANAGEMENT_PERMISSION_MODE_UNSPECIFIED" | "MANAGEMENT_PERMISSION_MODE_ALL" | "MANAGEMENT_PERMISSION_MODE_RESTRICTED" | "MANAGEMENT_PERMISSION_MODE_READ_ONLY";
        access?: string;
        expiresAt?: Date;
        clearExpiresAt?: boolean;
      };
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "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, AccessLevel],  # optional
            "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": str,
            "updated_at": str,
            "last_used_at": str,  # optional
            "expires_at": str,  # optional
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      managementKey: {
        managementKeyId: string;
        name: string;
        permissionMode: "MANAGEMENT_PERMISSION_MODE_UNSPECIFIED" | "MANAGEMENT_PERMISSION_MODE_ALL" | "MANAGEMENT_PERMISSION_MODE_RESTRICTED" | "MANAGEMENT_PERMISSION_MODE_READ_ONLY";
        access?: string;
        tokenPrefix: string;
        status: "MANAGEMENT_KEY_STATUS_UNSPECIFIED" | "MANAGEMENT_KEY_STATUS_ACTIVE" | "MANAGEMENT_KEY_STATUS_DISABLED" | "MANAGEMENT_KEY_STATUS_REVOKED";
        createdById?: string;
        updatedById?: string;
        createdAt: Date;
        updatedAt: Date;
        lastUsedAt?: Date;
        expiresAt?: Date;
      };
    }
    ```
  </CodeGroup>
</Expandable>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.