Authentication

Overview

Every request to /v1/* must include an Authorization header with a valid API token:

Authorization: Bearer <your_token>

Requests without a valid token return TOKEN_INVALID (401).

Creating a token

Open the dashboard
Click New token
Copy the token, or come back and view it in the dashboard later.

Generating a new token replaces the previous one. The old token stops working right away.

Using your token

Pass the token in the Authorization header on every request:

curl -X POST https://api.thewitn.com/v1/events \
  -H "Authorization: Bearer <your_token>"

Never include your API token in client-side code or commit it to source control. Store it in an environment variable or a secrets manager.

Example: environment variable

# .env
WITN_API_KEY=your_token_here

const res = await fetch('https://api.thewitn.com/v1/events', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WITN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    key: 'support:ticket:1001',
    action: 'signed',
    agent_key: 'support',
    customer_key: 'acme',
  }),
})

Token security model

Property	Detail
Format	Tokens are HMAC-signed and verified on every request without a database lookup.
Retrieval	Your token stays viewable in the dashboard, so you can copy it again at any time.
Scope	Tokens are scoped to your account. They can access all resources owned by your user.
Rotation	Generate a new token to replace the old one. The previous token stops working right away.

Error responses

Situation	Code	Status
`Authorization` header missing	`TOKEN_INVALID`	401
Wrong scheme (not `Bearer`)	`TOKEN_INVALID`	401
Token signature invalid or malformed	`TOKEN_INVALID`	401

See TOKEN_INVALID for the full error reference.