The Cequence Unified API Edge (UAP Edge) provides a standardized endpoint for ingesting API transaction data into the Cequence UAP platform. This article explains the data format, authentication requirements, and integration steps needed to send traffic data to UAP Edge. Details on the data format are available in a separate article.

UAP Edge accepts traffic from Cequence Defenders and Sensors, third-party API gateways (Apigee, Kong), custom integrations, and middleware components. The unified approach uses a single, extensible JSON format that consolidates data for both bot mitigation and API security analysis.

API endpoints and authentication details

Authentication setup

Prerequisites

Before sending data to UAP Edge, create a Traffic Management profile and obtain credentials.

1. Log in to the Cequence Web Dashboard.
2. Select the settings icon (top right) General Settings Clients Add New Client.
3. Enter a client name in the Client Name field. This name serves as your client ID.
4. Enable the Traffic Management toggle.
5. Optionally, enter a whole number of seconds in Token Lifespan to change the token expiration from the default of 1800 seconds.
6. Select Save. A dialog box displays the client secret.
7. Select the blue copy icon to copy the secret to your clipboard, then select Close.
8. Store the client ID from earlier in this procedure and the client secret for use in your integration. The client secret will not be displayed again in the UI for security reasons.

Authentication flow

UAP Edge uses OAuth 2.0 client credentials flow. Request an access token from the token endpoint, then include the access token in subsequent API requests.

Token request example

Replace <YOUR_TENANT_DOMAIN>, <CLIENT_ID>, and <CLIENT_SECRET> with your actual values.

curl -s "https://auth.<YOUR_TENANT_DOMAIN>/auth/realms/cequence/protocol/openid-connect/token" \
  -H "Accept: application/json" \
  -d "client_id=<CLIENT_ID>" \
  -d "client_secret=<CLIENT_SECRET>" \
  -d "grant_type=client_credentials"

Token response example

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 1800,
  "refresh_expires_in": 0,
  "token_type": "Bearer"
}

API request with token

Include the access token in the Authorization header when submitting transactions.

curl -s -X POST "https://edge.<YOUR_TENANT_DOMAIN>/api-transactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Accept: */*" \
  -H "Cache-Control: no-cache" \
  -H "Connection: keep-alive" \
  -d @transaction-data.json

Endpoint structure

Cequence provides two distinct endpoints for submitting transaction data.

https://edge.<tenant-domain>/api-transaction    # Single transaction
https://edge.<tenant-domain>/api-transactions   # Bulk transactions

For example, when your tenant is demo.cequence.cloud:

• Auth: https://auth.demo.cequence.cloud/auth/realms/cequence/protocol/openid-connect/token
• Single: https://edge.demo.cequence.cloud/api-transaction
• Bulk: https://edge.demo.cequence.cloud/api-transactions

Single transaction endpoint

Use /api-transaction to submit a single HTTP transaction for processing.

Bulk transactions endpoint

Use /api-transactions (note the plural form) to submit multiple transactions in a single API request for batch processing.

Data format specification

Transaction object schema

All transactions must contain the following top-level structure.

{
  "timestamp": "string (required)",
  "version": "string (required)",
  "transaction-id": "string (optional)",
  "request": { object (required) },
  "response": { object (required) },
  "txn-meta-data": { object (optional) }
}

Top-level fields

Request object schema

{
  "http-method": "string (required)",
  "uri-query-fragment": "string (required)",
  "connection": { object (required) },
  "headers": [ array (required) ],
  "client-ip": "string (optional)",
  "http-version": "string (optional)",
  "http-scheme": "string (optional)",
  "host": "string (optional)",
  "body": { object (optional) }
}

Connection object schema

{
  "connection-ip": "string (required)",
  "server-ip": "string (required)",
  "connection-port": integer (optional),
  "server-port": integer (optional),
  "transaction-depth": integer (optional),
  "ssl-signature": "string (optional)",
  "ssl-cipher-bytes": "string (optional)",
  "ssl-extensions-bytes": "string (optional)"
}

Headers format

Headers are provided as an array of strings in the format Header-Name: base64-encoded-value. Header values must be base64-encoded to support binary data and special characters.

"headers": [
  "User-Agent: TW96aWxsYS81LjAgKFdpbmRvd3MgTlQgMTAuMCk=",
  "Content-Type: YXBwbGljYXRpb24vanNvbg==",
  "Authorization: QmVhcmVyIGV5SmhiR2NpT2lKSVV6STFOaUo5..."
]

Body object schema

The body object is optional. Include the body object only when the request or response has a body. Always base64-encode body data. The length field should reflect the original byte length before encoding. Empty bodies can omit the body field entirely.

{
  "length": integer (required),
  "data": "string (required)"
}

Response object schema

{
  "status-code": "string (required)",
  "headers": [ array (required) ],
  "body": { object (optional) }
}

Bulk transactions format

The bulk endpoint accepts a JSON object containing an array of transaction records.

{
  "data": [
    {
      "timestamp": "1640995200",
      "version": "1.0",
      "transaction-id": "unique-request-id-12345",
      "request": { ... },
      "response": { ... },
      "txn-meta-data": { ... }
    }
  ]
}

Transaction metadata

The txn-meta-data object provides additional context about the transaction source. Third-party integrations should include only source info; the remaining metadata fields are reserved for internal Cequence data sources.

{
  "txn-meta-data": {
    "source_info": {
      "version": "2.0.0",
      "type": "Custom-integration"
    }
  }
}

Client IP address extraction

The Cequence UAP platform can automatically extract the client's real IP address using one of two approaches.

Provide the client IP address directly

If you extract the client IP address at your edge, include the IP address in the client-ip field.

{
  "client-ip": "203.0.113.45",
  ...
}

Let the Cequence UAP platform extract the IP address

When you omit the client-ip field, leave it empty, or set it to -, the Cequence UAP platform extracts the client IP address from standard headers including X-Forwarded-For, X-Real-IP, CF-Connecting-IP, and other configured real-IP headers.

Encoding requirements

All header values and body content must be base64-encoded. Do not send headers as key-value objects. Header values support binary data and special characters through base64 encoding.