Issue an ingest key

curl --request POST \
  --url https://app.hookie.ai/admin/api/projects/{project_id}/ingest-keys \
  --header 'Content-Type: application/json' \
  --cookie hookie_session= \
  --data '
{
  "name": "<string>",
  "dataset_default": "default",
  "require_signature": false,
  "expires_at": "2023-11-07T05:31:56Z",
  "ip_allowlist": [
    "203.0.113.0/24",
    "2001:db8::/32"
  ]
}
'

const options = {
  method: 'POST',
  headers: {cookie: 'hookie_session=', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    dataset_default: 'default',
    require_signature: false,
    expires_at: '2023-11-07T05:31:56Z',
    ip_allowlist: ['203.0.113.0/24', '2001:db8::/32']
  })
};

fetch('https://app.hookie.ai/admin/api/projects/{project_id}/ingest-keys', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://app.hookie.ai/admin/api/projects/{project_id}/ingest-keys"

payload = {
    "name": "<string>",
    "dataset_default": "default",
    "require_signature": False,
    "expires_at": "2023-11-07T05:31:56Z",
    "ip_allowlist": ["203.0.113.0/24", "2001:db8::/32"]
}
headers = {
    "cookie": "hookie_session=",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "<string>",
  "key": "<string>",
  "signing_secret": "<string>",
  "key_prefix": "<string>",
  "expires_at": "2023-11-07T05:31:56Z",
  "ip_allowlist": [
    "<string>"
  ],
  "ingest_key": {
    "id": "<string>",
    "name": "<string>",
    "key_prefix": "<string>",
    "dataset_default": "<string>",
    "require_signature": 0,
    "ip_allowlist": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "last_used_at": "2023-11-07T05:31:56Z",
    "revoked_at": "2023-11-07T05:31:56Z",
    "expires_at": "2023-11-07T05:31:56Z",
    "replaced_by": "<string>",
    "status": "active"
  }
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

POST

admin

api

projects

{project_id}

ingest-keys

Issue an ingest key

curl --request POST \
  --url https://app.hookie.ai/admin/api/projects/{project_id}/ingest-keys \
  --header 'Content-Type: application/json' \
  --cookie hookie_session= \
  --data '
{
  "name": "<string>",
  "dataset_default": "default",
  "require_signature": false,
  "expires_at": "2023-11-07T05:31:56Z",
  "ip_allowlist": [
    "203.0.113.0/24",
    "2001:db8::/32"
  ]
}
'

const options = {
  method: 'POST',
  headers: {cookie: 'hookie_session=', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    dataset_default: 'default',
    require_signature: false,
    expires_at: '2023-11-07T05:31:56Z',
    ip_allowlist: ['203.0.113.0/24', '2001:db8::/32']
  })
};

fetch('https://app.hookie.ai/admin/api/projects/{project_id}/ingest-keys', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://app.hookie.ai/admin/api/projects/{project_id}/ingest-keys"

payload = {
    "name": "<string>",
    "dataset_default": "default",
    "require_signature": False,
    "expires_at": "2023-11-07T05:31:56Z",
    "ip_allowlist": ["203.0.113.0/24", "2001:db8::/32"]
}
headers = {
    "cookie": "hookie_session=",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "<string>",
  "key": "<string>",
  "signing_secret": "<string>",
  "key_prefix": "<string>",
  "expires_at": "2023-11-07T05:31:56Z",
  "ip_allowlist": [
    "<string>"
  ],
  "ingest_key": {
    "id": "<string>",
    "name": "<string>",
    "key_prefix": "<string>",
    "dataset_default": "<string>",
    "require_signature": 0,
    "ip_allowlist": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "last_used_at": "2023-11-07T05:31:56Z",
    "revoked_at": "2023-11-07T05:31:56Z",
    "expires_at": "2023-11-07T05:31:56Z",
    "replaced_by": "<string>",
    "status": "active"
  }
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

{
  "error": "<string>",
  "retry_after": 123,
  "upgrade_url": "<string>",
  "reason": "<string>",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:read",
  "granted_scopes": [
    "<string>"
  ],
  "manage_url": "<string>",
  "scheme": "<string>",
  "max_members": 123,
  "members": 123,
  "customer_id": "<string>",
  "customer_name": "<string>",
  "account_id": "<string>",
  "terms_version": "<string>",
  "claim_required": true
}

Authorizations

hookie_session

string

required

The console's sealed session cookie, set by WorkOS AuthKit. Mutating requests also require the X-Requested-With CSRF header.

Headers

Idempotency-Key

string

Makes a POST safe to retry for 24 hours: the same key, credential, path and body returns the stored response (Idempotent-Replayed: true) instead of running again. 422 if the key was used for a different request; 409 while the first is in flight.

Required string length: 1 - 255

Path Parameters

project_id

string

required

Project id (UUID) belonging to the caller workspace.

Body

application/json

name

string

required

Required string length: 1 - 80

dataset_default

string

default:default

Where POST /v1/ingest/{ingest_key} (no dataset segment) stores an event none of the project's mapping rules routes: the whole payload (the identity mapping) as one record in this dataset, fanned out to destinations, the live stream, AI triggers and workflows like any other record, and charged the same single quota event. The 201 then answers routed: [""], records: 1, fallback: true. A dataset named in the path (POST /v1/ingest/{ingest_key}/{dataset}) is written directly and endpoint URLs never use it. Must be a valid dataset name; a non-string value is stored as default. Listed with the key, carried over on rotation, and fixed at creation (#280).

Pattern: ^[A-Za-z][A-Za-z0-9_]{0,62}$

require_signature

boolean

default:false

Only the literal true enables it. When enabled a signing secret is generated and returned once.

expires_at

string<date-time> | null

When the key stops authenticating, at ingest and on /v1/stream alike. Must be in the future; null means never. A key past it answers 404 'Unknown ingest key', exactly like a revoked one.

ip_allowlist

string[] | null

IP addresses or CIDR ranges allowed to use this credential, validated exactly as the workspace and project allowlists are. [] or null removes the restriction (stored as null). A request must pass every allowlist that is set: this one, the project's and the workspace's. Refused requests get 403 'Source IP not allowed' and an ingest_ip_blocked audit row.

Maximum array length: 64

An IPv4 or IPv6 address, or a CIDR range.

Example:

["203.0.113.0/24", "2001:db8::/32"]

Response

Created. key is the full ik_live_ token and signing_secret the whsec_ value - both are shown exactly once and only the key hash / encrypted secret are stored.

string

required

key

string

required

ik_live_ followed by 48 hex characters.

signing_secret

string | null

required

Present only when require_signature was true; otherwise null.

key_prefix

string

The first 16 characters, which is all the list shows from now on.

expires_at

string<date-time> | null

ip_allowlist

string[]

The normalised allowlist; [] for any address.

ingest_key

object

The created ingest key, as GET by id returns it (#201).

Show child attributes

Get started

Concepts

CLI

Guides

API reference

Issue an ingest key

Authorizations

Headers

Path Parameters

Body

Response