Oligon Receipts is in private beta — request access.
API reference
API keys

API keys

Manage the sk_live_… / sk_test_… secrets used to call /v1/extract and the read endpoints. All endpoints below are JWT-authenticated (dashboard session); the keys they manage are the separate X-API-Key credentials.

MethodPathPermission
GET/v1/api-keysapikey:read
POST/v1/api-keysapikey:write
POST/v1/api-keys/{key_id}/revokeapikey:revoke
DELETE/v1/api-keys/{key_id}apikey:revoke
⚠️

The full secret (key) is returned only once — in the response of POST /v1/api-keys. There is no endpoint to retrieve it later. If you lose it, revoke the key and create a new one.

GET /v1/api-keys

List all keys for the actor's org, newest first. Secrets are not included.

curl https://api.receipts.oligontech.com/v1/api-keys \
  -H "Authorization: Bearer $JWT"

Response — 200 OK

[
  {
    "id":           "01HQX...",
    "name":         "Production server",
    "prefix":       "sk_live",
    "last4":        "x9k2",
    "scopes":       ["extract:read", "extract:write"],
    "is_live":      true,
    "revoked_at":   null,
    "last_used_at": "2026-06-09T12:01:33+00:00",
    "last_used_ip": "203.0.113.5",
    "created_at":   "2026-05-20T09:00:00+00:00"
  }
]

POST /v1/api-keys

Mint a new key. The plaintext key is in the response once — store it immediately.

Request body

FieldTypeRequiredNotes
namestringyes1–120 chars. Display label.
scopesstring[]noSubset of extract:read, extract:write, analytics:read, admin:write. Empty list = no scopes.
liveboolnofalse (default) → sk_test_…; true → sk_live_….
curl https://api.receipts.oligontech.com/v1/api-keys \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production","scopes":["extract:write"],"live":true}'

Response — 201 Created

{
  "id":           "01HQX...",
  "name":         "Production",
  "prefix":       "sk_live",
  "last4":        "x9k2",
  "scopes":       ["extract:write"],
  "is_live":      true,
  "revoked_at":   null,
  "last_used_at": null,
  "last_used_ip": null,
  "created_at":   "2026-06-09T12:00:00+00:00",
  "key":          "sk_live_aB3...x9k2"
}

400 validation_error if scopes contains an unknown value.

POST /v1/api-keys/{key_id}/revoke

Soft-revoke: sets revoked_at to now. The row stays for audit. Subsequent requests using the key fail with 401 authentication_failed.

curl -X POST https://api.receipts.oligontech.com/v1/api-keys/01HQX.../revoke \
  -H "Authorization: Bearer $JWT"

Returns the same ApiKeyOut shape as GET, now with revoked_at populated. 404 not_found if the key doesn't exist or belongs to another org.

DELETE /v1/api-keys/{key_id}

Hard-delete the row. Audit event is recorded first. Returns 204 No Content. 404 not_found if missing or cross-org.

curl -X DELETE https://api.receipts.oligontech.com/v1/api-keys/01HQX... \
  -H "Authorization: Bearer $JWT"

Prefer revoke over delete unless you need to clean up test data — revocation preserves the audit trail and the "last used" trace.

OAuthOrganization