Argusdocs

Authentication and keys

API keys are organisation-owned bearer tokens with a dk_ prefix. You see a key's secret exactly once, at creation; the server keeps only a fingerprint.

Source uses separate permissions

This page describes the existing Argus read API. Connected Source uses its own namespace, Source connection keys and explicit Source OAuth permissions. Existing Argus read credentials gain no write or supplier-tool permission. Follow Connect your agent for Source setup.

The scheme

Send the key as a bearer token on every request:

curl https://api.ducket.io/api/v1/coverage \
  -H "Authorization: Bearer dk_example_9hK2mQ4vX8wL1pR7"

API keys work on /api/v1/ paths and on the hosted MCP endpoint (see MCP server), always as the same bearer header. A key presented to any app route is refused, and an app session presented to a keyed path is refused the same way. The two credentials never cross.

Connectors sign in instead

An AI assistant added as a connector in claude.ai or ChatGPT does not use a key. It runs an OAuth sign-in against https://mcp.ducket.io where a member of your organisation approves one screen, and it receives a short-lived token it refreshes on its own. Setup is in MCP server.

The two credentials meet at the same place. A connector approval is bound to one organisation and resolves to that organisation's connector key, so it reads the identical licensed slice a key of that scope reads, and it is metered and rate limited the same way. It follows your plan the same way too: nothing about your subscription is baked into the token, so a change takes effect on the next request. Revoking the connector key stops every connection riding it.

Connector tokens are not API keys and cannot be used as one: they are issued only through the approval flow, never shown in the organisation page, and there is no way to mint one without a signed-in member.

Creating a key

An admin of your organisation opens the Organisation tab in Settings, names the key, picks its scope (full catalog or a vertical slice), and presses Create. The response shows the full secret once, with the warning to store it now. After that moment the server can never show it again: it stores only the first 12 characters (for display) and a SHA-256 fingerprint (for verification).

Rolling rotation

Rotating a key mints its successor with the same scope and stamps an expiry on the old key, 7 days out by default. Both keys verify during that window, so you can deploy the new secret without downtime; the old key then stops on its own. Two rules keep the lineage clean:

  • Rotation never extends a key. A key already expiring sooner keeps its earlier expiry.
  • Only the newest key in a lineage can be rotated. Rotating an already-replaced key is refused.

Revocation

Revoking a key stops it with no grace window, unlike rotation. Verified keys are cached briefly, so a revoked key stops being accepted across the whole service within about 30 seconds. Use revocation when a secret may have leaked; use rotation for routine replacement. Platform administrators can also revoke any key.

Refusal behavior

Verification fails closed. Every one of these returns 401: a missing or malformed token, an unknown key, a revoked key, an expired key, a key whose organisation no longer exists, and a storage error during verification itself. The API never serves a request it could not verify.

HTTP/1.1 401 Unauthorized
{"detail": "unauthorized"}