API Keys

API keys provide programmatic access to HatiData. Keys are scoped to environments, hashed with Argon2id before storage, and support automatic rotation with a grace period.

List API Keys

GET /v1/environments/{env_id}/api-keys

Lists all API keys for the environment. Key values are not returned -- only metadata. Requires Owner or Admin role.

Request:

curl https://api.hatidata.com/v1/environments/env_prod_x1y2/api-keys \
  -H "Authorization: Bearer <jwt>"

Response 200 OK:

{
  "data": [
    {
      "key_id": "key_a1b2c3",
      "name": "analytics-dashboard",
      "prefix": "hd_live_a1b2",
      "scopes": ["query:read", "schema:read"],
      "ip_allowlist": ["10.0.0.0/8"],
      "status": "active",
      "last_used_at": "2026-02-16T09:15:00Z",
      "expires_at": null,
      "created_at": "2026-01-15T10:00:00Z",
      "created_by": "usr_x1y2z3"
    },
    {
      "key_id": "key_d4e5f6",
      "name": "data-pipeline-agent",
      "prefix": "hd_live_d4e5",
      "scopes": ["query:read", "query:write", "schema:read", "agent:*"],
      "ip_allowlist": [],
      "status": "active",
      "last_used_at": "2026-02-16T10:30:00Z",
      "expires_at": "2026-06-15T10:00:00Z",
      "created_at": "2026-02-01T14:00:00Z",
      "created_by": "usr_x1y2z3"
    }
  ],
  "pagination": {
    "cursor": null,
    "has_more": false,
    "total": 2
  }
}

Create API Key

POST /v1/environments/{env_id}/api-keys

Creates a new API key. The plaintext key is returned only in this response -- it cannot be retrieved later. Requires Owner or Admin role.

Request:

curl -X POST https://api.hatidata.com/v1/environments/env_prod_x1y2/api-keys \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "langchain-agent",
    "scopes": ["query:read", "query:write", "schema:read", "agent:*"],
    "ip_allowlist": ["10.0.1.0/24", "10.0.2.0/24"],
    "expires_in_days": 90
  }'

Response 201 Created:

{
  "key_id": "key_g7h8i9",
  "name": "langchain-agent",
  "key": "hd_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "prefix": "hd_live_a1b2",
  "scopes": ["query:read", "query:write", "schema:read", "agent:*"],
  "ip_allowlist": ["10.0.1.0/24", "10.0.2.0/24"],
  "status": "active",
  "expires_at": "2026-05-17T10:00:00Z",
  "created_at": "2026-02-16T10:00:00Z",
  "created_by": "usr_x1y2z3"
}

Save Your Key

The key field is shown only once in the creation response. Store it securely. If lost, rotate the key to generate a new one.

Field	Type	Required	Description
name	string	Yes	Human-readable name
scopes	string[]	Yes	Permissions granted to this key
ip_allowlist	string[]	No	CIDR ranges allowed to use this key
expires_in_days	integer	No	Auto-expire after N days (omit for no expiration)

Available Scopes

Scope	Description
query:read	Execute SELECT queries
query:write	Execute INSERT, UPDATE, DELETE, CREATE, DROP
schema:read	Read table schemas and metadata
schema:write	Create and alter tables
policy:read	View policies
policy:write	Create, update, delete policies
user:read	List users
user:write	Invite, update, remove users
key:read	List API keys
key:write	Create, rotate, revoke API keys
audit:read	Read audit logs
billing:read	View usage and quotas
billing:write	Update quotas
webhook:read	List webhooks
webhook:write	Create, update, delete webhooks
environment:read	List environments
environment:write	Create, promote environments
agent:*	All agent-related operations

Wildcard scopes: Use * suffix to grant all sub-scopes (e.g., policy:* grants both policy:read and policy:write).

Rotate API Key

POST /v1/environments/{env_id}/api-keys/{key_id}/rotate

Generates a new key value. Both old and new keys are valid during the grace period (default: 72 hours). Requires Owner or Admin role.

Request:

curl -X POST https://api.hatidata.com/v1/environments/env_prod_x1y2/api-keys/key_a1b2c3/rotate \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "grace_period_hours": 48
  }'

Response 200 OK:

{
  "key_id": "key_a1b2c3",
  "new_key": "hd_live_n3w5ecr3tk3ya1b2c3d4e5f6g7h8i9j0",
  "new_prefix": "hd_live_n3w5",
  "old_key_expires_at": "2026-02-18T10:00:00Z",
  "grace_period_hours": 48,
  "rotated_at": "2026-02-16T10:00:00Z",
  "rotated_by": "usr_x1y2z3"
}

Field	Type	Required	Description
grace_period_hours	integer	No	Hours both keys remain valid (default: 72, max: 168)

Rotation Webhooks

If webhooks are configured, HatiData sends a key.rotated event when a key is rotated and a key.expiring event 24 hours before the old key expires.

Revoke API Key

DELETE /v1/environments/{env_id}/api-keys/{key_id}

Immediately revokes an API key. All requests using this key will return 401 Unauthorized. Requires Owner or Admin role.

Request:

curl -X DELETE https://api.hatidata.com/v1/environments/env_prod_x1y2/api-keys/key_d4e5f6 \
  -H "Authorization: Bearer <jwt>"

Response 200 OK:

{
  "key_id": "key_d4e5f6",
  "name": "data-pipeline-agent",
  "revoked": true,
  "revoked_at": "2026-02-16T12:00:00Z",
  "revoked_by": "usr_x1y2z3"
}

Immediate Effect

Key revocation takes effect immediately. There is no grace period. Ensure any services using this key have been updated before revoking.

Error Responses

Status	Code	Description
400	VALIDATION_ERROR	Invalid scopes or CIDR format
401	UNAUTHORIZED	Missing or invalid authentication
403	FORBIDDEN	Insufficient role or scope
404	NOT_FOUND	Key or environment not found
409	CONFLICT	Key name already exists in this environment