> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goliathdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate inbound webhook requests using a token URL or JWT.

Inbound webhooks support two authentication methods. Most integrations should use token auth. JWT is available for advanced OAuth clients.

***

## Token auth (recommended)

The webhook token is embedded directly in the URL path. No `Authorization` header is needed.

```
POST {WEBHOOK_BASE_URL}/{token}/contacts/create-with-ai
Content-Type: application/json
```

The token must be:

* A valid v4 UUID
* Matching an active `IncomingWebhook` row for your organization
* Not disabled by an org admin

If the token is invalid, missing, or belongs to a disabled webhook, the server returns:

```json theme={null}
401 Unauthorized

{ "error": "Unauthorized" }
```

<Warning>
  Treat the full webhook URL as a secret. It is bearer-equivalent — the token in the URL is the only credential protecting your org's data. Do not commit it to source control or expose it in client-side code.
</Warning>

***

## JWT auth (advanced)

The contact endpoints also accept a standard JWT with the `contacts:create` scope. This is intended for OAuth clients and server-to-server integrations that already manage tokens.

When using JWT, pass the token in the `Authorization` header:

```
POST {WEBHOOK_BASE_URL}/contacts/create-with-ai
Authorization: Bearer {jwt}
Content-Type: application/json
```

<Note>
  When using JWT auth, omit the token segment from the URL path. The `{token}/` segment is only used for token-based auth.
</Note>

***

## Auth errors

| Status | Cause                                                         |
| ------ | ------------------------------------------------------------- |
| `401`  | Token is invalid, not found, or the webhook has been disabled |
| `401`  | JWT is missing, expired, or lacks the required scope          |
| `405`  | Request was not a `POST`                                      |