API Keys and Authentication

Sending requests to Coop

To authenticate the requests you send to Coop, add an HTTP header to every API request with your organization’s API key. You can find or manage your API key in Settings → API Keys in the Coop UI.

Format the header as follows:

X-API-KEY: <<apiKey>>
Content-Type: application/json

You can rotate your API key at any time from the same page. After rotating, update any applications or scripts that use the previous key.

Verifying incoming requests from Coop

To verify that an incoming request to your Action APIs (or other webhooks) was sent by Coop, you can check the request signature. Coop signs each HTTP request it sends to your endpoints and includes the signature in a header. You use a webhook signature verification key (public key) to verify that signature.

• Your webhook signature verification key is shown in Settings → API Keys under “Webhook Signature Verification Key”. You can generate a new key there when needed; after rotation, update your verification logic with the new public key.

Validating requests with the signature header

Coop sends the signature in a Coop-Signature header (or coop-signature depending on the client). To validate an incoming HTTP request:

1. Hash the request body using SHA-256. Use the raw request body (binary) as the input to the hash.
2. Base64-decode the value in the Coop-Signature header to obtain the raw binary signature.
3. Verify the signature using your public key. Coop uses RSASSA-PKCS1-v1_5 with SHA-256: decrypt/verify the signature with your public key and confirm it matches the hash from step 1. Use your language’s crypto library (e.g. Web Crypto, OpenSSL, or standard crypto packages) for RSASSA-PKCS1-v1_5 verification.

Example (JavaScript / Node)

// Your public signing key in PEM format (from Settings → API Keys)
const pem = `-----BEGIN PUBLIC KEY-----
...your key...
-----END PUBLIC KEY-----`;

const pemHeader = "-----BEGIN PUBLIC KEY-----";
const pemFooter = "-----END PUBLIC KEY-----";
const publicKeyPem = pem.substring(
  pemHeader.length,
  pem.length - pemFooter.length
);

const publicKeyBuffer = Buffer.from(publicKeyPem, "base64");
const requestBodyBuffer = Buffer.from(req.body, "utf8");
const signature = Buffer.from(req.headers["coop-signature"], "base64");

const publicKey = await crypto.subtle.importKey(
  "spki",
  publicKeyBuffer,
  { name: "RSASSA-PKCS1-v1_5", hash: { name: "SHA-256" } },
  false,
  ["verify"]
);

const isValid = await crypto.subtle.verify(
  "RSASSA-PKCS1-v1_5",
  publicKey,
  signature,
  requestBodyBuffer
);

Adjust header name (coop-signature vs Coop-Signature) and body encoding to match how your server receives the request.