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:

Bearer Token Example (curl)

Bash

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

---

HTTP Basic Authentication

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

HTTP Basic Auth Example (curl)

Bash

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

---

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 . Coviu supports the following schemes:

• Basic
• Post
• JWT (with shared secret)

Configuration Required

• Authorization Server URL
• Client ID
• Client Secret

Flow

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

Token Server Response

HTTP

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

JSON

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

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

Webhook Request With OAuth Token (curl)

Bash

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

---

OAuth Client Credentials: Basic

Credentials are passed in the Authorization header.

OAuth Basic Example (curl)

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"

---

OAuth Client Credentials: Post

Credentials are sent in the request body.

OAuth Post Example (curl)

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"

---

OAuth Client Credentials: JWT

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

OAuth JWT Example (curl)

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"

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.

• 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.