API Keys SDK Reference

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)

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();

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"]],
    "include_budget": Optional[bool],
}

{
  limit?: number;
  startingAfter?: string;
  endingBefore?: string;
  projectId?: string;
  status?: string;
  search?: string;
  ownerType?: string;
  permissionMode?: string;
  includeBudget?: boolean;
}

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],
        "budget": {  # optional
            "budget_id": Optional[str],
            "scope": {  # optional
                "workspace": {},  # optional
                "project": {  # optional
                    "project_id": Optional[str],
                },
                "identity": {  # optional
                    "identity_external_id": Optional[str],
                },
                "api_key": {  # optional
                    "api_key_id": Optional[str],
                },
                "provider": {  # optional
                    "provider": Optional[str],
                },
                "model": {  # optional
                    "model_id": Optional[str],
                },
            },
            "match": {  # optional
                "cel": Optional[str],
            },
            "limits": {  # optional
                "period": Optional[Literal["BUDGET_PERIOD_UNSPECIFIED", "BUDGET_PERIOD_DAILY", "BUDGET_PERIOD_WEEKLY", "BUDGET_PERIOD_MONTHLY", "BUDGET_PERIOD_YEARLY", "BUDGET_PERIOD_ONE_TIME"]],
                "amount": Optional[float],
                "token_limit": Optional[float],
            },
            "rate_limit": {  # optional
                "requests_per_minute": Optional[int],
            },
            "is_active": Optional[bool],
            "expires_at": date,
            "created_at": date,
            "updated_at": date,
            "usage": {  # optional
                "amount": Optional[float],
                "tokens": Optional[float],
                "requests": Optional[int],
            },
        },
    },
    "has_more": bool,
}

{
  object: string;
  data: {
    apiKeyId: string;
    name: string;
    owner: {
      user?: {
        userId: string;
      };
      serviceAccount?: {};
    };
    projectScope: {
      all?: {};
      single?: {
        projectId: string;
      };
    };
    permissionMode: string;
    access?: Record<string, number>;
    tokenPrefix: string;
    status: string;
    createdById?: string;
    updatedById?: string;
    createdAt: Date;
    updatedAt: Date;
    lastUsedAt?: Date;
    expiresAt?: Date;
    legacyTokenFamily?: string;
    legacyKeyId?: string;
    budget?: {
      budgetId?: string;
      scope?: {
        workspace?: {};
        project?: {
          projectId?: string;
        };
        identity?: {
          identityExternalId?: string;
        };
        apiKey?: {
          apiKeyId?: string;
        };
        provider?: {
          provider?: string;
        };
        model?: {
          modelId?: string;
        };
      };
      match?: {
        cel?: string;
      };
      limits?: {
        period?: string;
        amount?: number;
        tokenLimit?: number;
      };
      rateLimit?: {
        requestsPerMinute?: number;
      };
      isActive?: boolean;
      expiresAt?: Date;
      createdAt?: Date;
      updatedAt?: Date;
      usage?: {
        amount?: number;
        tokens?: number;
        requests?: number;
      };
    };
  };
  hasMore: boolean;
}

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)

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();

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,
}

{
  name: string;  // required
  owner?: {
    user?: {
      userId: string;  // required
    };
    serviceAccount?: {};
  };
  projectScope?: {
    all?: {};
    single?: {
      projectId: string;  // required
    };
  };
  permissionMode?: string;
  access?: Record<string, number>;
  expiresAt?: 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],
        "budget": {  # optional
            "budget_id": Optional[str],
            "scope": {  # optional
                "workspace": {},  # optional
                "project": {  # optional
                    "project_id": Optional[str],
                },
                "identity": {  # optional
                    "identity_external_id": Optional[str],
                },
                "api_key": {  # optional
                    "api_key_id": Optional[str],
                },
                "provider": {  # optional
                    "provider": Optional[str],
                },
                "model": {  # optional
                    "model_id": Optional[str],
                },
            },
            "match": {  # optional
                "cel": Optional[str],
            },
            "limits": {  # optional
                "period": Optional[Literal["BUDGET_PERIOD_UNSPECIFIED", "BUDGET_PERIOD_DAILY", "BUDGET_PERIOD_WEEKLY", "BUDGET_PERIOD_MONTHLY", "BUDGET_PERIOD_YEARLY", "BUDGET_PERIOD_ONE_TIME"]],
                "amount": Optional[float],
                "token_limit": Optional[float],
            },
            "rate_limit": {  # optional
                "requests_per_minute": Optional[int],
            },
            "is_active": Optional[bool],
            "expires_at": date,
            "created_at": date,
            "updated_at": date,
            "usage": {  # optional
                "amount": Optional[float],
                "tokens": Optional[float],
                "requests": Optional[int],
            },
        },
    },
    "token": str,
}

{
  apiKey: {
    apiKeyId: string;
    name: string;
    owner: {
      user?: {
        userId: string;
      };
      serviceAccount?: {};
    };
    projectScope: {
      all?: {};
      single?: {
        projectId: string;
      };
    };
    permissionMode: string;
    access?: Record<string, number>;
    tokenPrefix: string;
    status: string;
    createdById?: string;
    updatedById?: string;
    createdAt: Date;
    updatedAt: Date;
    lastUsedAt?: Date;
    expiresAt?: Date;
    legacyTokenFamily?: string;
    legacyKeyId?: string;
    budget?: {
      budgetId?: string;
      scope?: {
        workspace?: {};
        project?: {
          projectId?: string;
        };
        identity?: {
          identityExternalId?: string;
        };
        apiKey?: {
          apiKeyId?: string;
        };
        provider?: {
          provider?: string;
        };
        model?: {
          modelId?: string;
        };
      };
      match?: {
        cel?: string;
      };
      limits?: {
        period?: string;
        amount?: number;
        tokenLimit?: number;
      };
      rateLimit?: {
        requestsPerMinute?: number;
      };
      isActive?: boolean;
      expiresAt?: Date;
      createdAt?: Date;
      updatedAt?: Date;
      usage?: {
        amount?: number;
        tokens?: number;
        requests?: number;
      };
    };
  };
  token: string;
}

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)

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();

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 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)

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();

Show Parameters

{
    "api_key_id": str,  # required
    "include_budget": Optional[bool],
}

{
  apiKeyId: string;  // required
  includeBudget?: boolean;
}

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],
        "budget": {  # optional
            "budget_id": Optional[str],
            "scope": {  # optional
                "workspace": {},  # optional
                "project": {  # optional
                    "project_id": Optional[str],
                },
                "identity": {  # optional
                    "identity_external_id": Optional[str],
                },
                "api_key": {  # optional
                    "api_key_id": Optional[str],
                },
                "provider": {  # optional
                    "provider": Optional[str],
                },
                "model": {  # optional
                    "model_id": Optional[str],
                },
            },
            "match": {  # optional
                "cel": Optional[str],
            },
            "limits": {  # optional
                "period": Optional[Literal["BUDGET_PERIOD_UNSPECIFIED", "BUDGET_PERIOD_DAILY", "BUDGET_PERIOD_WEEKLY", "BUDGET_PERIOD_MONTHLY", "BUDGET_PERIOD_YEARLY", "BUDGET_PERIOD_ONE_TIME"]],
                "amount": Optional[float],
                "token_limit": Optional[float],
            },
            "rate_limit": {  # optional
                "requests_per_minute": Optional[int],
            },
            "is_active": Optional[bool],
            "expires_at": date,
            "created_at": date,
            "updated_at": date,
            "usage": {  # optional
                "amount": Optional[float],
                "tokens": Optional[float],
                "requests": Optional[int],
            },
        },
    },
}

{
  apiKey: {
    apiKeyId: string;
    name: string;
    owner: {
      user?: {
        userId: string;
      };
      serviceAccount?: {};
    };
    projectScope: {
      all?: {};
      single?: {
        projectId: string;
      };
    };
    permissionMode: string;
    access?: Record<string, number>;
    tokenPrefix: string;
    status: string;
    createdById?: string;
    updatedById?: string;
    createdAt: Date;
    updatedAt: Date;
    lastUsedAt?: Date;
    expiresAt?: Date;
    legacyTokenFamily?: string;
    legacyKeyId?: string;
    budget?: {
      budgetId?: string;
      scope?: {
        workspace?: {};
        project?: {
          projectId?: string;
        };
        identity?: {
          identityExternalId?: string;
        };
        apiKey?: {
          apiKeyId?: string;
        };
        provider?: {
          provider?: string;
        };
        model?: {
          modelId?: string;
        };
      };
      match?: {
        cel?: string;
      };
      limits?: {
        period?: string;
        amount?: number;
        tokenLimit?: number;
      };
      rateLimit?: {
        requestsPerMinute?: number;
      };
      isActive?: boolean;
      expiresAt?: Date;
      createdAt?: Date;
      updatedAt?: Date;
      usage?: {
        amount?: number;
        tokens?: number;
        requests?: number;
      };
    };
  };
}

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)

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

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

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

  console.log(result);
}

run();

Show Parameters

{
    "api_key_id": str,  # required
}

{
  apiKeyId: string;  // 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)

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();

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],
}

{
  apiKeyId: string;  // required
  updateApiKeyRequest: {  // required
    name?: string;
    status?: string;
    permissionMode?: string;
    access?: Record<string, number>;
    projectScope?: {
      all?: {};
      single?: {
        projectId: string;  // required
      };
    };
    expiresAt?: Date;
    clearExpiresAt?: boolean;
  };
}

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],
        "budget": {  # optional
            "budget_id": Optional[str],
            "scope": {  # optional
                "workspace": {},  # optional
                "project": {  # optional
                    "project_id": Optional[str],
                },
                "identity": {  # optional
                    "identity_external_id": Optional[str],
                },
                "api_key": {  # optional
                    "api_key_id": Optional[str],
                },
                "provider": {  # optional
                    "provider": Optional[str],
                },
                "model": {  # optional
                    "model_id": Optional[str],
                },
            },
            "match": {  # optional
                "cel": Optional[str],
            },
            "limits": {  # optional
                "period": Optional[Literal["BUDGET_PERIOD_UNSPECIFIED", "BUDGET_PERIOD_DAILY", "BUDGET_PERIOD_WEEKLY", "BUDGET_PERIOD_MONTHLY", "BUDGET_PERIOD_YEARLY", "BUDGET_PERIOD_ONE_TIME"]],
                "amount": Optional[float],
                "token_limit": Optional[float],
            },
            "rate_limit": {  # optional
                "requests_per_minute": Optional[int],
            },
            "is_active": Optional[bool],
            "expires_at": date,
            "created_at": date,
            "updated_at": date,
            "usage": {  # optional
                "amount": Optional[float],
                "tokens": Optional[float],
                "requests": Optional[int],
            },
        },
    },
}

{
  apiKey: {
    apiKeyId: string;
    name: string;
    owner: {
      user?: {
        userId: string;
      };
      serviceAccount?: {};
    };
    projectScope: {
      all?: {};
      single?: {
        projectId: string;
      };
    };
    permissionMode: string;
    access?: Record<string, number>;
    tokenPrefix: string;
    status: string;
    createdById?: string;
    updatedById?: string;
    createdAt: Date;
    updatedAt: Date;
    lastUsedAt?: Date;
    expiresAt?: Date;
    legacyTokenFamily?: string;
    legacyKeyId?: string;
    budget?: {
      budgetId?: string;
      scope?: {
        workspace?: {};
        project?: {
          projectId?: string;
        };
        identity?: {
          identityExternalId?: string;
        };
        apiKey?: {
          apiKeyId?: string;
        };
        provider?: {
          provider?: string;
        };
        model?: {
          modelId?: string;
        };
      };
      match?: {
        cel?: string;
      };
      limits?: {
        period?: string;
        amount?: number;
        tokenLimit?: number;
      };
      rateLimit?: {
        requestsPerMinute?: number;
      };
      isActive?: boolean;
      expiresAt?: Date;
      createdAt?: Date;
      updatedAt?: Date;
      usage?: {
        amount?: number;
        tokens?: number;
        requests?: number;
      };
    };
  };
}

Orq SDK

Orq CLI

Platform APIs

Gateway APIs

Enterprise APIs (coming soon)

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

API Keys

List API Keys

Create an API Key

List Capabilities

Retrieve an API Key

Delete an API Key

Update an API Key