API keys

An API key is a signing key pair bound to one tenancy. The Platform generates it, shows you the private half once, and keeps only the public half. Nothing secret ever travels. Every request carries a signature over what that request does, the moment, the method, the path, the body, and the Platform verifies it against the public half it stored.

The private half is shown exactly once, at minting. The Platform stores nothing that can sign, so a key you lose cannot be recovered. It is revoked and replaced.

What a key is

A minted key is three parts, separated by underscores.

Part	What it is
`capsk`	This Platform’s mark. A key found in a log or a screenshot is attributable, and therefore revocable
Fingerprint	43 characters. Non-secret: it is printed at the mint, listed in the Console, and written on every request line the key authorises
Seed	43 characters. What signs. It exists in exactly one place, which is wherever you put it

capsk_<fingerprint>_<seed>

Cut the parts by position, not by splitting on the underscore. Both halves are base64url, whose alphabet contains the underscore, a split comes apart on roughly three keys in four, depending on nothing but what the random source drew.

Signing a request

The signature is taken over a canonical string of five lines, joined by newlines with nothing after the last.

Line	What it carries
1	The Unix timestamp, in seconds, that you stamp
2	The method, uppercase
3	The path with its query, exactly as you send it
4	The lowercase hex SHA-256 of the body, the digest of the empty string when there is no body
5	The `Idempotency-Key` you send, or the empty string

There is no other canonicalisation. Query parameters are not reordered and nothing is normalised: you sign what you send and send what you signed. The signature is Ed25519 over that string, and the header presents it:

Authorization: Capcells-Ed25519 fp=<fingerprint>,ts=<unix>,sig=<base64>

The signature is standard base64 without padding. The timestamp must be within 5 minutes of the Platform’s clock, either way, and the window binds however far outside it a stamp lies. A request stamped four centuries ahead is refused exactly as one stamped six minutes ahead is.

Test vectors

Check your signer against these before your first request. They are produced by the same code that verifies your requests, and the Platform’s own test fails if they drift. The key below is a seed of thirty-two zero bytes, so any Ed25519 library reproduces it.


Fingerprint	`AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA`
Seed (base64url)	`AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA`
Public half (base64)	`O2onvM62pC1io6jQKm8Nc2UyFXcd4kOmOsBIoYtZ2ik`

Signing POST /v1/tenants/capyplazo/clients with the body {"id":"client-0001"}, no idempotency token, at ts=1787000000:

Canonical string

1787000000
POST
/v1/tenants/capyplazo/clients
4e91b6493bf2969d2108dfb2671302199bae114ec71a42ac10a30c616517c7c2

The fifth line is empty, and the string ends there, no trailing newline. That empty line is the idempotency token this request does not carry.

Authorization header

Capcells-Ed25519 fp=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA,ts=1787000000,sig=zr8WqEEm7XAJ4sX9F2wcvmlDSUHoxK60GJEY0cVkoK56AXBIPPKhSNKyajlPZMeKt4BsyLwqJLTH9WOHJRHFAw

A reference signer

# Needs OpenSSL 1.1.1 or later. LibreSSL, which is /usr/bin/openssl on macOS,
# cannot sign Ed25519: point OPENSSL at a real one.
OPENSSL="${OPENSSL:-openssl}"

capcells_key_pem() {           # $1 the capsk_ key -> a PEM on stdout
  local seed="${1:50:43}"
  printf -- '-----BEGIN PRIVATE KEY-----\n'
  printf '302e020100300506032b657004220420%s' \
    "$(printf '%s=' "$seed" | tr '_-' '/+' | base64 -d | xxd -p -c 64)" |
    xxd -r -p | base64
  printf -- '-----END PRIVATE KEY-----\n'
}

capcells_sign() {              # $1 key  $2 method  $3 path  $4 body  $5 idem
  local ts digest pem canon sig
  ts="$(date +%s)"
  digest="$(printf '%s' "${4:-}" | "$OPENSSL" dgst -sha256 | sed 's/^.*= //')"
  pem="$(mktemp)"; canon="$(mktemp)"
  trap 'rm -f "$pem" "$canon"' RETURN
  capcells_key_pem "$1" > "$pem"
  printf '%s\n%s\n%s\n%s\n%s' "$ts" "$2" "$3" "$digest" "${5:-}" > "$canon"
  sig="$("$OPENSSL" pkeyutl -sign -rawin -inkey "$pem" -in "$canon" |
    base64 | tr -d '\n=')"
  [ -n "$sig" ] || { echo "cannot sign: $OPENSSL does not do Ed25519" >&2; return 2; }
  printf 'Capcells-Ed25519 fp=%s,ts=%s,sig=%s' "${1:6:43}" "$ts" "$sig"
}

import base64, hashlib, time
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey

def unpad(s: str) -> bytes:
    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))

def sign(key: str, method: str, path: str, body: bytes = b"", idem: str = "") -> str:
    fingerprint, seed = key[6:49], key[50:93]
    private = Ed25519PrivateKey.from_private_bytes(unpad(seed))

    ts = int(time.time())
    canonical = "\n".join([
        str(ts), method.upper(), path,
        hashlib.sha256(body).hexdigest(), idem,
    ]).encode()

    sig = base64.b64encode(private.sign(canonical)).decode().rstrip("=")
    return f"Capcells-Ed25519 fp={fingerprint},ts={ts},sig={sig}"

import (
    "crypto/ed25519"
    "crypto/sha256"
    "encoding/base64"
    "encoding/hex"
    "fmt"
    "strconv"
    "strings"
    "time"
)

func Sign(key, method, path string, body []byte, idem string) (string, error) {
    seed, err := base64.RawURLEncoding.DecodeString(key[50:93])
    if err != nil {
        return "", err
    }
    private := ed25519.NewKeyFromSeed(seed)

    ts := time.Now().Unix()
    digest := sha256.Sum256(body)
    canonical := strings.Join([]string{
        strconv.FormatInt(ts, 10), strings.ToUpper(method), path,
        hex.EncodeToString(digest[:]), idem,
    }, "\n")

    sig := base64.RawStdEncoding.EncodeToString(ed25519.Sign(private, []byte(canonical)))
    return fmt.Sprintf("Capcells-Ed25519 fp=%s,ts=%d,sig=%s", key[6:49], ts, sig), nil
}

Refusals

Every unusable presentation receives the same answer: 401, with WWW-Authenticate: Capcells-Ed25519 and the body {"error":"this route requires a signed credential","code":"unauthenticated"}. The same answer, byte for byte, for all of these:

What was wrong
No `Authorization` header, or more than one
A scheme that is not `Capcells-Ed25519`, a bearer token is refused here
A fingerprint naming no key of yours
A signature that does not verify
A timestamp more than 5 minutes from the Platform’s clock, however far
A key you revoked, or one that expired
An `Idempotency-Key` longer than 255 bytes, the Platform signs the empty fifth line for a key it will not read, so your signature no longer matches the string it builds

Nothing in the answer tells them apart, deliberately: a caller that could would learn which of its guesses was closer. The first thing to check is your clock, because it is the only one of these that can appear suddenly on a signer that worked yesterday. The last row is the one that reads as a puzzle, so it is worth stating plainly: an over-long key is refused as unauthenticated rather than as a bad key, because the door promises exactly two answers before any handler runs and a third would be a new thing to read. Keep keys short, a UUID is 36 bytes, and the case never arises. At the Console door, which carries no signature, the same key is 400 invalid_idempotency_key.

The 5-minute window bounds a replay, and what closes it is the act’s own idempotency rather than the window. A captured request replayed inside those five minutes reaches the route again, and on the two routes with no reference of yours — creating a Configuration, or a version of one — it performs the act a second time unless you sent an Idempotency-Key. The key is part of the signed string, so a captured request cannot have one added or changed; sending one is what makes the replay harmless. Retries carries the rule.

When the key is fine

A 403 is the other answer, and it means the opposite of a 401: the signature verified, the key is live, and the request is still refused. There are two, and they are separate codes because the remedies have nothing to do with each other.

Code	The sentence	What to do
`not_permitted_tenant`	the credential does not act for the tenant named in this path	Fix the tenancy in the path. A key acts for exactly one, and the one it acts for is not the one you addressed
`not_permitted_scope`	the credential’s scope does not cover this request	Obtain a credential of the other scope. A `read` key was used for a write, and no scope can be widened, mint a `write` key at the Console

Neither names an identifier and neither names a scope. Which tenancy your key acts for is something you already know; which one you asked for is in your own URL. What the Platform will not do is answer “no” in a way that lets a caller discover other tenants by asking.

Rotating and revoking

Mint the new key first, prove it works, then revoke the old one. keys are independent, so both are live during the handover, the reverse order leaves a window where you cannot call anything. Revoking binds on the very next request. There is no window in which a revoked key still works.

Limits

It will not	Why
Accept an unsigned request, under any setting	Two accepted presentations is a branch asking how to verify. There is no such branch and no setting that creates one
Accept a key you generated	The private half is drawn by the Platform from a cryptographic source. There is no field through which yours could arrive
Show you a private half twice	It is stored nowhere. What the Platform keeps verifies and cannot sign
Tell you which refusal you met	See above. The clock is the first thing to check

Getting started

Authentication

Lending

Risk

Markets

What a key is

Signing a request

Test vectors

A reference signer

Refusals

When the key is fine

Rotating and revoking

Limits

​What a key is

​Signing a request

​Test vectors

​A reference signer

​Refusals

​When the key is fine

​Rotating and revoking

​Limits

What a key is

Signing a request

Test vectors

A reference signer

Refusals

When the key is fine

Rotating and revoking

Limits