Skip to main content

API Keys

Use API keys when a backend service (not a logged-in user) needs to call the Orqio REST API.

API keys are:

  • Scoped to a workspace (create separate keys for staging and prod)
  • Shown only once at creation time (copy it immediately)
  • Revocable (a revoked key stops working immediately)

Before you create a key​

  • Confirm which workspace the integration should use (staging first, then prod)
  • Decide key ownership (team/service name) and naming convention
  • Prepare a secret manager location where the key will be stored

Create an API key (Orqio UI)​

  1. Switch to the target workspace (start with staging).
  2. Open API Keys in the left navigation.
  3. Click Create API Key.
  4. Give the key a descriptive name (example: staging-crm-sync).
  5. Copy the key from the one-time reveal dialog and store it in a secret manager.
Treat API keys as secrets

Never commit API keys into Git or paste them into tickets. Rotate and revoke keys regularly.

Use a consistent format:

{workspace}-{integration}-{purpose}

Examples:

  • staging-salesforce-sync-read
  • prod-support-webhook-write

Use an API key in requests​

Orqio accepts API keys in either of these forms:

  • x-api-key: pk_...
  • Authorization: Bearer pk_...

Example: list contacts (API key supported)​

curl -sS "https://app.orqio.io/public/api/v1/orgs/$ORG_ID/workspaces/$WORKSPACE_ID/contacts" \
  -H "x-api-key: $ORQIO_API_KEY"
Endpoint support

The customer-facing API on app.orqio.io/public/api is API-key-first and currently includes contacts, contact custom attributes, and trigger webhook invocation endpoints.

Operational best practices​

  • Create keys per service, not shared across unrelated systems
  • Keep separate keys for staging and production
  • Rotate keys regularly (for example, every 60–90 days)
  • Revoke keys immediately when ownership changes or exposure is suspected

Troubleshooting checklist​

  • Invalid format: API keys use a public.secret composite format (typically starting with pk_).
  • 401 Unauthorized: header missing or malformed.
  • 403 revoked/expired: create a new key and revoke the old one.
  • Wrong workspace: keys are workspace-scoped; ensure key and URL target the same workspace.