Authentication & Authorization

openssl genpkey -algorithm ed25519 -out clc-ed25519-private.pem
openssl pkey -in clc-ed25519-private.pem -pubout -out clc-ed25519-public.pem

CLC-Ed25519
<timestamp>
<method>
<path + canonicalized query>
<sha256(body) hex>

package main

import (
	"crypto/ed25519"
	"crypto/rand"
	"crypto/sha256"
	"crypto/x509"
	"encoding/base64"
	"encoding/hex"
	"encoding/pem"
	"fmt"
	"io"
	"net/http"
	"os"
	"strconv"
	"strings"
	"time"
)

const (
	keyID   = "clk_live_7f3a9c2e"
	baseURL = "https://api.clc.solutions"
)

// Your Ed25519 private key, generated by you and never sent to CLC.
func loadKey(path string) ed25519.PrivateKey {
	pemBytes, _ := os.ReadFile(path)
	block, _ := pem.Decode(pemBytes)
	key, _ := x509.ParsePKCS8PrivateKey(block.Bytes)
	return key.(ed25519.PrivateKey)
}

// One key per logical operation. Reuse the same value when you retry, so CLC
// replays the original response instead of closing the facility twice.
func newIdempotencyKey() string {
	b := make([]byte, 16)
	rand.Read(b)
	return hex.EncodeToString(b)
}

func signedRequest(priv ed25519.PrivateKey, method, path string, body []byte, idempotencyKey string) (*http.Response, error) {
	ts := strconv.FormatInt(time.Now().Unix(), 10)
	sum := sha256.Sum256(body)
	canonical := strings.Join([]string{"CLC-Ed25519", ts, method, path, hex.EncodeToString(sum[:])}, "\n")
	sig := ed25519.Sign(priv, []byte(canonical))

	req, err := http.NewRequest(method, baseURL+path, strings.NewReader(string(body)))
	if err != nil {
		return nil, err
	}
	req.Header.Set("X-CLC-Key-Id", keyID)
	req.Header.Set("X-CLC-Timestamp", ts)
	req.Header.Set("X-CLC-Signature", base64.StdEncoding.EncodeToString(sig))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Idempotency-Key", idempotencyKey)
	return http.DefaultClient.Do(req)
}

func main() {
	priv := loadKey("clc-ed25519-private.pem")
	body := []byte(`{"reason":"borrower_request"}`)
	resp, err := signedRequest(priv, "POST", "/v1/facilities/fac_9k2m/close", body, newIdempotencyKey())
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	out, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(out))
}

import crypto from "node:crypto";
import { readFileSync } from "node:fs";

// Your Ed25519 private key, generated by you and never sent to CLC.
const privateKey = crypto.createPrivateKey(readFileSync("clc-ed25519-private.pem"));

const KEY_ID = "clk_live_7f3a9c2e";
const BASE_URL = "https://api.clc.solutions";

async function signedRequest(method, path, body = "", idempotencyKey) {
  const ts = Math.floor(Date.now() / 1000).toString();
  const bodyHash = crypto.createHash("sha256").update(body).digest("hex");
  const canonical = ["CLC-Ed25519", ts, method, path, bodyHash].join("\n");
  // Ed25519: the algorithm argument must be null, since the hash is built in.
  const signature = crypto.sign(null, Buffer.from(canonical), privateKey);

  return fetch(BASE_URL + path, {
    method,
    headers: {
      "X-CLC-Key-Id": KEY_ID,
      "X-CLC-Timestamp": ts,
      "X-CLC-Signature": signature.toString("base64"),
      "Content-Type": "application/json",
      "Idempotency-Key": idempotencyKey,
    },
    body: body || undefined,
  });
}

// Close a facility on behalf of your borrower.
// One key per logical operation. Reuse the same value when you retry, so CLC
// replays the original response instead of closing the facility twice.
const res = await signedRequest("POST", "/v1/facilities/fac_9k2m/close", '{"reason":"borrower_request"}', crypto.randomUUID());
console.log(res.status, await res.json());

import base64, hashlib, time, uuid, requests
from cryptography.hazmat.primitives.serialization import load_pem_private_key

# Your Ed25519 private key, generated by you and never sent to CLC.
with open("clc-ed25519-private.pem", "rb") as f:
    private_key = load_pem_private_key(f.read(), password=None)

KEY_ID = "clk_live_7f3a9c2e"
BASE_URL = "https://api.clc.solutions"

def signed_request(method, path, body=b"", idempotency_key=""):
    ts = str(int(time.time()))
    body_hash = hashlib.sha256(body).hexdigest()
    canonical = "\n".join(["CLC-Ed25519", ts, method, path, body_hash])
    signature = base64.b64encode(private_key.sign(canonical.encode())).decode()
    headers = {
        "X-CLC-Key-Id": KEY_ID,
        "X-CLC-Timestamp": ts,
        "X-CLC-Signature": signature,
        "Content-Type": "application/json",
        "Idempotency-Key": idempotency_key,
    }
    return requests.request(method, BASE_URL + path, data=body, headers=headers)

# Close a facility on behalf of your borrower.
# One key per logical operation. Reuse the same value when you retry, so CLC
# replays the original response instead of closing the facility twice.
r = signed_request("POST", "/v1/facilities/fac_9k2m/close", b'{"reason":"borrower_request"}', str(uuid.uuid4()))
print(r.status_code, r.json())

{
  "type": "https://developers.clc.solutions/errors/idempotency_key_conflict",
  "title": "Conflict",
  "status": 409,
  "code": "idempotency_key_conflict",
  "detail": "Idempotency key reused with a different request."
}