API Reference

API Keys

Programmatically manage your org's API keys.

Requires an API-key account context

These endpoints require a live API key that belongs to a credit account plus the listed operational scopes. Internal bearer tokens and sandbox-only keys are not a provisioning path for creating or inspecting production API keys.

List Keys

GET/v1/api-keys0 credits

bash

curl -H "Authorization: Bearer ss_live_..." \
  "https://api.hillwinds.ai/v1/api-keys"

Create Key

POST/v1/api-keys0 credits

Parameter	Type	Description
`scopes`required	string[]	Scopes to grant to the child key. Data-read scopes include read:companies and read:personnel; operational scopes include tags:write, data-flags:write, reports:write, keys:read, keys:write, credits:read, and usage:read. The parent key must already have any scope it grants.
`name`	string	Display name for the child key.
`field_tier`	basic \| advanced	Default tier for every entity. Per-entity overrides come from the parent key (see entity_field_tiers below).
`key_type`	live \| test	Defaults to live. Use test for sandbox-only keys (ss_test_… prefix).
`entity_field_tiers`	object	Read-only — copied from the parent key on creation. Map of entity → basic\|advanced. You can't set this manually; provision a parent key with the right entitlements instead.
`field_tiers`	object	Read-only — per-entity basic/advanced field allowlists, copied from the parent key.

bash

curl -X POST -H "Authorization: Bearer ss_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Clay - Production",
    "scopes": ["read:companies", "read:personnel"],
    "field_tier": "advanced",
    "key_type": "live"
  }' \
  "https://api.hillwinds.ai/v1/api-keys"

The response includes the full key value:

json

{
  "ok": true,
  "data": {
    "id": "key_a1b2c3d4",
    "key": "ss_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "key_prefix": "ss_live_a1b2c3",
    "name": "Clay - Production",
    "scopes": ["read:companies", "read:personnel"],
    "field_tier": "advanced",
    "key_type": "live",
    "created_at": "2026-04-22T14:30:00Z"
  }
}

Save the key now

The full key value is returned only in this response. After this, only the key_prefix is visible. If you lose it, rotate.

Revoke Key

DELETE/v1/api-keys/:key_id0 credits

bash

curl -X DELETE -H "Authorization: Bearer ss_live_..." \
  "https://api.hillwinds.ai/v1/api-keys/key_a1b2c3d4"

Rotate Key

POST/v1/api-keys/:key_id/rotate0 credits

Generates a new secret for an existing key. The old secret is invalidated immediately. The new full key is returned exactly once in this response — same shape as the create endpoint.

bash

curl -X POST -H "Authorization: Bearer ss_live_..." \
  "https://api.hillwinds.ai/v1/api-keys/key_a1b2c3d4/rotate"

PreviousReview Flags Next Credits

Need a key?

Keys are issued by our team, not a signup form. Book a 25-minute walkthrough and you'll leave with sandbox and live credentials.

Get access Explore the platform