---
agentTools:
  projectIndex: https://coviu.readme.io/llms.txt
---

# Authentication

Customers using Webhooks may wish to add authentication to their webhook endpoints, in order to prevent unauthorized users from calling these endpoints.

Coviu supports several different authentication schemes:

* Bearer Token
* HTTP Basic Authentication
* OAuth Client Credentials:

  * Basic
  * Post
  * JWT

***

## Bearer Token

Coviu sends the token as a `Bearer` token in the `Authorization` header.

If you configure a token of `990192803`, Coviu dispatches the webhook like this:

<details>
<summary><code>Bearer Token Example (curl)</code></summary>

```bash
curl -X POST "$WEBHOOK_URL" \
  --header 'Authorization: Bearer 990192803' \
  --data '{ "type": "event:type", "payload": {} }'
```

</details>

***

## HTTP Basic Authentication

You specify a **username** and **password**, which Coviu sends via standard Basic Auth.

<details>
<summary><code>HTTP Basic Auth Example (curl)</code></summary>

```bash
curl -X POST "$WEBHOOK_URL" \
  -u "$USERNAME:$PASSWORD" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data '{ "type": "event:type", "payload": {} }'
```

</details>

***

## OAuth Client Credentials

Coviu can authenticate via OAuth 2.0 Client Credentials.

For a good overview of the different ways client credentials can be supplied, see: [SecureAuth: OAuth Client Secret Authentication](https://docs.secureauth.com/ciam/en/oauth-client-secret-authentication.html) . Coviu supports the following schemes:

* Basic
* Post
* JWT (with shared secret)

### Configuration Required

* **Authorization Server URL**
* **Client ID**
* **Client Secret**

### Flow

[block:image]
{
  "images": [
    {
      "image": [
        "https://files.readme.io/55e690110fa1a1d30adbe375f6938402b8eb6a00e06aa0cc66b178cb504a20a0-mermaid-diagram-12883604887502855-20250805-0218-default-bgLight.png",
        "",
        ""
      ],
      "align": "center"
    }
  ]
}
[/block]

1. Coviu sends a Client Credentials request to your token server.
2. Expects a response like:

<details>
<summary><code>Token Server Response</code></summary>

```http
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
```

```json
{
  "access_token": "243o5ein23o45ien234o5ein23o4523",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

</details>

3. Coviu caches the access token and uses it in subsequent webhook requests:

<details>
<summary><code>Webhook Request With OAuth Token (curl)</code></summary>

```bash
curl -X POST "$WEBHOOK_SERVER_URL" \
  --header "Authorization: Bearer 243o5ein23o45ien234o5ein23o4523"
```

</details>

***

### OAuth Client Credentials: Basic

Credentials are passed in the Authorization header.

<details>
<summary><code>OAuth Basic Example (curl)</code></summary>

```bash
curl -X POST "$AUTHORIZATION_SERVER_URL" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-raw "grant_type=client_credentials"
```

</details>

***

### OAuth Client Credentials: Post

Credentials are sent in the request body.

<details>
<summary><code>OAuth Post Example (curl)</code></summary>

```bash
curl -X POST "$AUTHORIZATION_SERVER_URL" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  -F "grant_type=client_credentials" \
  -F "client_id=$CLIENT_ID" \
  -F "client_secret=$CLIENT_SECRET"
```

</details>

***

### OAuth Client Credentials: JWT

The client secret is used to sign a JWT using the HS256 algorithm. No secret is sent directly.

<details>
<summary><code>OAuth JWT Example (curl)</code></summary>

```bash
curl -X POST "$AUTHORIZATION_SERVER_URL" \
  -F "grant_type=client_credentials" \
  -F "client_id=$CLIENT_ID" \
  -F "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  -F "client_assertion=$JWT"
```

</details>

**JWT Claims:**

| Claim | Description                               |
| ----- | ----------------------------------------- |
| `iss` | Client ID                                 |
| `sub` | Client ID                                 |
| `aud` | Webhook URL                               |
| `iat` | Issued at (epoch seconds)                 |
| `exp` | Expires (5 mins after iat, epoch seconds) |

***

## Limitations

If any of these limitations impact compatibility, contact [Coviu Support](mailto:support@coviu.com).

* Extra form fields or JWT claims are **not supported**.
* **Auth0**:

  * Auth0 requires sending through an `"audience"` field. As we don’t support this, Auth0 users are advised to set the “Default Audience” in Tenant Settings.
  * `"organization"` field (for Auth0 Organizations) is not supported.
* JWT-based Client Credentials:

  * Only supported via **shared secret**
  * Only **HS256** algorithm
  * **Public/private keypairs** are **not** supported.