Wiro Docs Authentication
This section as Markdown: View Download

Authentication

Secure your API requests with signature-based or simple key authentication.

Overview

Wiro supports two authentication methods. You choose the method when creating a project and can switch it later in the project's settings on the Projects page. Your API key and secret stay the same, and the change applies right away, so your requests must then use the new method.

Signature-Based Authentication

Uses HMAC-SHA256 to sign every request. The API secret is never sent with your requests, but it is needed to make the signature, so sign requests on your own server. Never put the API secret in browser or mobile app code.

How it works

  1. Generate a nonce Use a unix timestamp or random integer
  2. Concatenate Combine: API_SECRET + NONCE
  3. Create HMAC-SHA256 hash Use your API_KEY as the secret key
  4. Send as headers Include the signature, nonce, and API key in request headers
SIGNATURE = HMAC-SHA256(key=API_KEY, message=API_SECRET + NONCE)

Required Headers

Parameter Type Required Description
x-api-key string Yes Your project API key
x-signature string Yes HMAC-SHA256(API_SECRET + NONCE, API_KEY)
x-nonce string Yes Unix timestamp or random integer

Comparison

Feature Signature-Based API Key Only
Security High: the secret is never sent over the wire Moderate: the key is sent with every request
Complexity Requires HMAC computation Single header
Best for Server-side apps, production backends Server-side, internal tools
Leaked API key Not enough: the secret is also needed Enough to call the API

How to Choose

  • Building a browser or mobile app? Have the app call your own backend, and call Wiro from there. Never put your API key or secret in the app.
  • Running a server-side backend with controlled access? API Key Only is simpler.
  • Unsure? Default to Signature-Based, which is always the safer option.

Using Auth with Agent Endpoints

The same authentication headers work for every UserAgent/* and UserAgentOAuth/* endpoint. Example:

curl -X POST "https://api.wiro.ai/v1/UserAgent/Message/Send" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${YOUR_API_KEY}" \
  -d '{
    "useragentguid": "your-useragent-guid",
    "message": "What are the latest campaign insights?"
  }'

Signature-based projects add x-nonce and x-signature exactly as shown in the Run example. The signing algorithm is identical. See Agent Overview for the full agent API reference.