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

# API Keys SDK Reference

> Manage Orq.ai API keys with the Node.js and Python SDKs: create, list, update, and delete keys and inspect the capabilities each key grants.

## API Keys

### List API Keys

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.

<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.api_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.apiKeys.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],
        "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"]],  # optional
        "permission_mode": List[Literal["PERMISSION_MODE_UNSPECIFIED", "PERMISSION_MODE_ALL", "PERMISSION_MODE_RESTRICTED", "PERMISSION_MODE_READ_ONLY"]],  # optional
        "include_budget": Optional[bool],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      limit?: number;
      startingAfter?: string;
      endingBefore?: string;
      projectId?: string;
      status?: "API_KEY_STATUS_UNSPECIFIED" | "API_KEY_STATUS_ACTIVE" | "API_KEY_STATUS_DISABLED" | "API_KEY_STATUS_REVOKED";
      search?: string;
      ownerType?: ("OWNER_TYPE_UNSPECIFIED" | "OWNER_TYPE_USER" | "OWNER_TYPE_SERVICE_ACCOUNT")[];
      permissionMode?: ("PERMISSION_MODE_UNSPECIFIED" | "PERMISSION_MODE_ALL" | "PERMISSION_MODE_RESTRICTED" | "PERMISSION_MODE_READ_ONLY")[];
      includeBudget?: boolean;
    }
    ```
  </CodeGroup>
</Expandable>

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

<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.api_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.apiKeys.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
        "owner": {  # optional
            "user": {  # optional
                "user_id": str,  # required
            },
            "service_account": Dict[str, Any],  # optional
        },
        "project_scope": {  # optional
            "all": Dict[str, Any],  # 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, AccessLevel],  # optional
        "expires_at": str,  # optional
        "mcp_access": {  # optional
            "deny_all": Optional[bool],
            "allowed_mcp_gateway_ids": List[str],  # optional
            "toolset_ids": List[str],  # optional
            "allowed_filesystem_ids": List[str],  # optional
        },
        "labels": Dict[str, str],  # optional
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      name: string;  // required
      owner?: {
        user?: {
          userId: string;  // required
        };
        serviceAccount?: Record<string, unknown>;
      };
      projectScope?: {
        all?: Record<string, unknown>;
        single?: {
          projectId: string;  // required
        };
      };
      permissionMode?: "PERMISSION_MODE_UNSPECIFIED" | "PERMISSION_MODE_ALL" | "PERMISSION_MODE_RESTRICTED" | "PERMISSION_MODE_READ_ONLY";
      access?: string;
      expiresAt?: Date;
      mcpAccess?: {
        denyAll?: boolean;
        allowedMcpGatewayIds?: string[];
        toolsetIds?: string[];
        allowedFilesystemIds?: string[];
      };
      labels?: Record<string, string>;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,
        "name": str,
        "workspace_id": str,
        "token": str,
        "active": Optional[bool],
        "is_legacy": Optional[bool],
        "source": Optional[str],
        "budget": Dict[str, Any],  # optional
        "expiration": str,  # optional
        "projects": List[str],  # optional
        "created_by_id": Optional[str],
        "updated_by_id": Optional[str],
        "created": str,  # optional
        "updated": str,  # optional
        "consumption": Optional[float],
        "token_consumption": Optional[float],
        "requests_per_minute_consumption": Optional[float],
        "owner": Dict[str, Any],  # optional
        "project_scope": Dict[str, Any],  # optional
        "permission_mode": Optional[str],
        "access": Dict[str, str],  # optional
        "token_prefix": Optional[str],
        "status": Optional[str],
        "constraints": Dict[str, Any],  # optional
        "mcp_access": Dict[str, Any],  # optional
        "legacy_token_family": Optional[str],
        "legacy_key_id": Optional[str],
        "last_used_at": str,  # optional
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      name: string;
      workspaceId: string;
      token: string;
      active?: boolean;
      isLegacy?: boolean;
      source?: string;
      budget?: Record<string, any>;
      expiration?: Date;
      projects?: string[];
      createdById?: string;
      updatedById?: string;
      created?: Date;
      updated?: Date;
      consumption?: number;
      tokenConsumption?: number;
      requestsPerMinuteConsumption?: number;
      owner?: Record<string, any>;
      projectScope?: Record<string, any>;
      permissionMode?: string;
      access?: Record<string, string>;
      tokenPrefix?: string;
      status?: string;
      constraints?: Record<string, any>;
      mcpAccess?: Record<string, any>;
      legacyTokenFamily?: string;
      legacyKeyId?: string;
      lastUsedAt?: Date;
    }
    ```
  </CodeGroup>
</Expandable>

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

<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.api_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.apiKeys.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", "DOMAIN_GROUP_PLATFORM", "DOMAIN_GROUP_GATEWAY"]],
            "allowed_scopes": List[Literal["SCOPE_MODE_ALL", "SCOPE_MODE_SINGLE"]],  # optional
            "readable": Optional[bool],
            "writable": Optional[bool],
            "extra_write_verbs": List[str],  # optional
        }],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      domains: {
        id?: string;
        displayName?: string;
        group?: "DOMAIN_GROUP_WORKSPACE_ADMIN" | "DOMAIN_GROUP_PLATFORM" | "DOMAIN_GROUP_GATEWAY";
        allowedScopes?: ("SCOPE_MODE_ALL" | "SCOPE_MODE_SINGLE")[];
        readable?: boolean;
        writable?: boolean;
        extraWriteVerbs?: string[];
      }[];
    }
    ```
  </CodeGroup>
</Expandable>

### Retrieve an API Key

Retrieves the metadata for an existing API key by its unique identifier. The raw secret is returned only once, at creation; the `token` field in this response carries the key prefix.

<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.api_keys.get(api_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.apiKeys.get({
      apiKeyId: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "api_key_id": str,  # required
        "include_budget": Optional[bool],
    }
    ```

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

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,
        "name": str,
        "workspace_id": str,
        "token": str,
        "active": Optional[bool],
        "is_legacy": Optional[bool],
        "source": Optional[str],
        "budget": Dict[str, Any],  # optional
        "expiration": str,  # optional
        "projects": List[str],  # optional
        "created_by_id": Optional[str],
        "updated_by_id": Optional[str],
        "created": str,  # optional
        "updated": str,  # optional
        "consumption": Optional[float],
        "token_consumption": Optional[float],
        "requests_per_minute_consumption": Optional[float],
        "owner": Dict[str, Any],  # optional
        "project_scope": Dict[str, Any],  # optional
        "permission_mode": Optional[str],
        "access": Dict[str, str],  # optional
        "token_prefix": Optional[str],
        "status": Optional[str],
        "constraints": Dict[str, Any],  # optional
        "mcp_access": Dict[str, Any],  # optional
        "legacy_token_family": Optional[str],
        "legacy_key_id": Optional[str],
        "last_used_at": str,  # optional
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      name: string;
      workspaceId: string;
      token: string;
      active?: boolean;
      isLegacy?: boolean;
      source?: string;
      budget?: Record<string, any>;
      expiration?: Date;
      projects?: string[];
      createdById?: string;
      updatedById?: string;
      created?: Date;
      updated?: Date;
      consumption?: number;
      tokenConsumption?: number;
      requestsPerMinuteConsumption?: number;
      owner?: Record<string, any>;
      projectScope?: Record<string, any>;
      permissionMode?: string;
      access?: Record<string, string>;
      tokenPrefix?: string;
      status?: string;
      constraints?: Record<string, any>;
      mcpAccess?: Record<string, any>;
      legacyTokenFamily?: string;
      legacyKeyId?: string;
      lastUsedAt?: Date;
    }
    ```
  </CodeGroup>
</Expandable>

### Delete an API Key

Permanently deletes an API key. The key is revoked immediately; in-flight requests using it will fail. 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:

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

      # Use the SDK ...

  ```

  ```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() {
    await orq.apiKeys.delete({
      apiKeyId: "<id>",
    });

  }

  run();
  ```
</CodeGroup>

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

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

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

<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.api_keys.update(api_key_id="<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.apiKeys.update({
      apiKeyId: "<id>",
      updateApiKeyRequest: {},
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "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, AccessLevel],  # optional
        "project_scope": {  # optional
            "all": Dict[str, Any],  # optional
            "single": {  # optional
                "project_id": str,  # required
            },
        },
        "expires_at": str,  # optional
        "clear_expires_at": Optional[bool],
        "mcp_access": {  # optional
            "deny_all": Optional[bool],
            "allowed_mcp_gateway_ids": List[str],  # optional
            "toolset_ids": List[str],  # optional
            "allowed_filesystem_ids": List[str],  # optional
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      apiKeyId: string;  // required
      updateApiKeyRequest: {  // required
        name?: string;
        status?: "API_KEY_STATUS_UNSPECIFIED" | "API_KEY_STATUS_ACTIVE" | "API_KEY_STATUS_DISABLED" | "API_KEY_STATUS_REVOKED";
        permissionMode?: "PERMISSION_MODE_UNSPECIFIED" | "PERMISSION_MODE_ALL" | "PERMISSION_MODE_RESTRICTED" | "PERMISSION_MODE_READ_ONLY";
        access?: string;
        projectScope?: {
          all?: Record<string, unknown>;
          single?: {
            projectId: string;  // required
          };
        };
        expiresAt?: Date;
        clearExpiresAt?: boolean;
        mcpAccess?: {
          denyAll?: boolean;
          allowedMcpGatewayIds?: string[];
          toolsetIds?: string[];
          allowedFilesystemIds?: string[];
        };
      };
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,
        "name": str,
        "workspace_id": str,
        "token": str,
        "active": Optional[bool],
        "is_legacy": Optional[bool],
        "source": Optional[str],
        "budget": Dict[str, Any],  # optional
        "expiration": str,  # optional
        "projects": List[str],  # optional
        "created_by_id": Optional[str],
        "updated_by_id": Optional[str],
        "created": str,  # optional
        "updated": str,  # optional
        "consumption": Optional[float],
        "token_consumption": Optional[float],
        "requests_per_minute_consumption": Optional[float],
        "owner": Dict[str, Any],  # optional
        "project_scope": Dict[str, Any],  # optional
        "permission_mode": Optional[str],
        "access": Dict[str, str],  # optional
        "token_prefix": Optional[str],
        "status": Optional[str],
        "constraints": Dict[str, Any],  # optional
        "mcp_access": Dict[str, Any],  # optional
        "legacy_token_family": Optional[str],
        "legacy_key_id": Optional[str],
        "last_used_at": str,  # optional
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      name: string;
      workspaceId: string;
      token: string;
      active?: boolean;
      isLegacy?: boolean;
      source?: string;
      budget?: Record<string, any>;
      expiration?: Date;
      projects?: string[];
      createdById?: string;
      updatedById?: string;
      created?: Date;
      updated?: Date;
      consumption?: number;
      tokenConsumption?: number;
      requestsPerMinuteConsumption?: number;
      owner?: Record<string, any>;
      projectScope?: Record<string, any>;
      permissionMode?: string;
      access?: Record<string, string>;
      tokenPrefix?: string;
      status?: string;
      constraints?: Record<string, any>;
      mcpAccess?: Record<string, any>;
      legacyTokenFamily?: string;
      legacyKeyId?: string;
      lastUsedAt?: Date;
    }
    ```
  </CodeGroup>
</Expandable>


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