Skip to main content

Create an API token

Goal​

You'll mint a personal API key (dqk_…) in the UI, copy it once, use it as a Bearer token against the REST API and the SDKs, and revoke it when you're done.

Prereqs​

  • A running PLACEHOLDER Cloud and an account you can log into.
  • You know which org (and optionally which workspace) you want the key scoped to.

A personal API key inherits your org role and — if you scope it — your access to a single workspace. It's a credential that acts as you, so treat it like a password.

Steps​

  1. Log in to the UI.

  2. Open Settings → API keys.

  3. Click "New API key". Give it a readable name (ci-nightly, laptop-cli) so you can tell your keys apart later. Optionally pick a workspace to scope the key to a single workspace; leave it unset to inherit your full org access.

  4. Re-enter your password if prompted. Minting a key is step-up gated — if your session is older than the step-up window you'll be asked to confirm your password first.

  5. Copy the token now. The raw dqk_… token is shown exactly once, right after you create it. PLACEHOLDER Cloud stores only a hash, so it can't show it to you again. If you lose it, revoke the key and mint a new one.

Use it​

A dqk_… token is a Bearer token. Send it in the Authorization header against any REST endpoint:

curl -H "Authorization: Bearer dqk_..." \
  https://placeholder.example.com/api/v1/organizations/$ORG_ID/personal-api-keys

Both SDKs take the same token directly:

from dq_cloud import DQCloudClient

client = DQCloudClient(api_key="dqk_...", base_url="https://placeholder.example.com")
import { DQCloudClient } from "@dq-cloud/sdk";

const client = new DQCloudClient({ apiKey: "dqk_...", baseUrl: "https://placeholder.example.com" });

See Use the Python SDK and Use the TypeScript SDK for worked examples.

Revoke it​

In Settings → API keys, find the key by name and click Revoke (or DELETE /api/v1/organizations/{org_id}/personal-api-keys/{id}). You can only see and revoke your own keys. Revocation isn't instant — a revoked key may keep working for up to TOKEN_CACHE_TTL_SECONDS (default 5 seconds) while the cached lookup expires.

Verify​

  • The new key appears in the Settings → API keys list with its name, scope, and a blank "Last used" until its first request.
  • A request carrying the token returns 200; after you revoke it (and the cache TTL elapses) the same request returns 401.

Caveats​

  • Shown once. There's no way to retrieve the raw token after the create response. Lost key → revoke and re-mint.
  • Acts as you. The key carries your org role (and workspace scope if you set one). Anyone holding it has that access — store it in a secret manager, never in source control.
  • Rate-limited mint. Creating keys is capped per minute by rate_limit_personal_api_keys_per_minute (default 10) — see Configuration.
  • JWT session tokens are not interchangeable with dqk_ keys for the SDK; use a personal API key (or an agent dqa_ token) for non-interactive callers.