Authentication

Every KYA Pro request needs a bearer token in the Authorization header:

Authorization: Bearer <token>

There are two kinds of tokens. Which one you use depends on the endpoint you're calling.

Customer API tokens — kya_live_...

Use for: anything a person or your integration would call — account management, permissions, handoffs, compliance packs, and per-workspace ingest.

Format: starts with kya_live_ (test tokens start with kya_test_).

Scope: every token is tied to one workspace. There is no way to reach another workspace with a kya_live_ token.

How to obtain one

Two ways:

1. Get your first token at sign-in. When you finish email sign-in via POST /api/v1/accounts/verify, the response includes a token named default. Use it right away or issue a new one.
2. Issue additional tokens for CI, integrations, or per-service use. You need an existing kya_live_ token:

curl -X POST https://api.veldtlabs.ai/api/v1/accounts/tokens \
  -H "Authorization: Bearer $VELDT_KYA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-pipeline"}'

Storage rules

• Treat every kya_live_ token like a password. Never commit it to source control.
• List existing tokens (name and prefix only — the full secret is never shown again):

curl https://api.veldtlabs.ai/api/v1/accounts/tokens \
  -H "Authorization: Bearer $VELDT_KYA_TOKEN"

Revoke a leaked token:

curl -X DELETE https://api.veldtlabs.ai/api/v1/accounts/tokens/<token_id> \
  -H "Authorization: Bearer $VELDT_KYA_TOKEN"

Ingress tokens — for high-volume collectors

Use for: the event ingest endpoint (POST /api/v1/admin/agents/events/invocation) when you run a shared collector pulling data from many runtime instances. Ingress tokens use a faster path built for sustained ingest.

Format: free-form string set up by the operator via env vars.

Two flavors:

Scoped ingress tokens

Map one token to one workspace. Set up by your operator in the deployment runbook (self-hosted only). Callers just send the token — the server figures out the workspace:

curl -X POST https://api.veldtlabs.ai/api/v1/admin/agents/events/invocation \
  -H "Authorization: Bearer $INGRESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent_key": "billing.orchestrator", "outcome": "success"}'

Prefer this when you can. No cross-workspace risk — the token IS the workspace.

Fallback ingress token

Single shared token used by any collector. The caller MUST include tenant_id in the request body. Set up by your operator in the deployment runbook.

curl -X POST https://api.veldtlabs.ai/api/v1/admin/agents/events/invocation \
  -H "Authorization: Bearer $INGRESS_FALLBACK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "tenant_example",
    "agent_key": "billing.orchestrator",
    "outcome": "success"
  }'

If tenant_id is missing, the request is rejected with 403 (see errors).

Which token do I use?

The ingest endpoints accept either — pick based on volume and where the caller lives.

Missing or invalid tokens

See the errors reference for the full error format.