Signing
Create a non-exportable signing key, sign bytes with it, verify signatures, and pin a service account to its own keys. For how keys, versions and access work, see Signing.
The examples use $SCAIVAULT_API_KEY, a service-account API key whose roles grant the sign:* scopes. Messages and signatures travel as standard base64.
Create a signing key
| curl -X POST https://scaivault.scailabs.ai/api/v1/sign/keys \
-H "X-API-Key: $SCAIVAULT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"path": "sign/acme/release-manifest", "suite": "s3-ed25519", "name": "Release manifests"}'
|
| import httpx, os
resp = httpx.post(
"https://scaivault.scailabs.ai/api/v1/sign/keys",
headers={"X-API-Key": os.environ["SCAIVAULT_API_KEY"]},
json={"path": "sign/acme/release-manifest", "suite": "s3-ed25519", "name": "Release manifests"},
)
print(resp.json()["id"])
|
| const resp = await fetch("https://scaivault.scailabs.ai/api/v1/sign/keys", {
method: "POST",
headers: {
"X-API-Key": process.env.SCAIVAULT_API_KEY!,
"Content-Type": "application/json",
},
body: JSON.stringify({ path: "sign/acme/release-manifest", suite: "s3-ed25519", name: "Release manifests" }),
});
console.log((await resp.json()).id);
|
Response (201):
| {
"id": "sk_1a1bd6f2c10_4e8a91b0c3d7",
"path": "sign/acme/release-manifest",
"name": "Release manifests",
"suite": "s3-ed25519",
"status": "active",
"current_version": 1,
"hsm_backed": false,
"rate_limit_per_min": null
}
|
Use s2-ecdsa-p384 or s4-mldsa65 for the other suites. Add "rate_limit_per_min": 600 to cap the key at 600 signatures a minute. The key path can contain slashes and is unique within your tenant.
Sign a message
| MSG=$(printf 'release v2.4.0' | base64)
SIG=$(curl -s -X POST https://scaivault.scailabs.ai/api/v1/sign/keys/sign/acme/release-manifest/sign \
-H "X-API-Key: $SCAIVAULT_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"message_b64\": \"$MSG\"}" | jq -r .signature_b64)
|
| import base64, httpx, os
resp = httpx.post(
"https://scaivault.scailabs.ai/api/v1/sign/keys/sign/acme/release-manifest/sign",
headers={"X-API-Key": os.environ["SCAIVAULT_API_KEY"]},
json={"message_b64": base64.b64encode(b"release v2.4.0").decode()},
)
signature = base64.b64decode(resp.json()["signature_b64"])
|
| const resp = await fetch(
"https://scaivault.scailabs.ai/api/v1/sign/keys/sign/acme/release-manifest/sign",
{
method: "POST",
headers: { "X-API-Key": process.env.SCAIVAULT_API_KEY!, "Content-Type": "application/json" },
body: JSON.stringify({ message_b64: Buffer.from("release v2.4.0").toString("base64") }),
},
);
const { signature_b64, version } = await resp.json();
|
Response:
| {
"key_id": "sk_1a1bd6f2c10_4e8a91b0c3d7",
"version": 1,
"suite": "s3-ed25519",
"signature_b64": "q2X0m3C5…"
}
|
The key path goes into the URL as it is, slashes included — don't URL-encode them.
Verify a signature
Ask ScaiVault:
| curl -X POST https://scaivault.scailabs.ai/api/v1/sign/keys/sign/acme/release-manifest/verify \
-H "X-API-Key: $SCAIVAULT_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"message_b64\": \"$MSG\", \"signature_b64\": \"$SIG\"}"
|
| resp = httpx.post(
"https://scaivault.scailabs.ai/api/v1/sign/keys/sign/acme/release-manifest/verify",
headers={"X-API-Key": os.environ["SCAIVAULT_API_KEY"]},
json={
"message_b64": base64.b64encode(b"release v2.4.0").decode(),
"signature_b64": base64.b64encode(signature).decode(),
},
)
print(resp.json()) # {"valid": true, "matched_version": 1}
|
| const check = await fetch(
"https://scaivault.scailabs.ai/api/v1/sign/keys/sign/acme/release-manifest/verify",
{
method: "POST",
headers: { "X-API-Key": process.env.SCAIVAULT_API_KEY!, "Content-Type": "application/json" },
body: JSON.stringify({ message_b64: Buffer.from("release v2.4.0").toString("base64"), signature_b64 }),
},
);
console.log(await check.json()); // { valid: true, matched_version: 1 }
|
A wrong signature returns 200 with "valid": false — it is an answer, not an error. Without version, ScaiVault checks every version of the key, so signatures made before a rotation still verify; pass "version": 2 to accept only one.
Verify without calling ScaiVault
Most verifiers shouldn't need a ScaiVault credential at all. Fetch the public key once, ship it with your verifier, and check signatures locally:
| curl https://scaivault.scailabs.ai/api/v1/sign/keys/sign/acme/release-manifest/public-key \
-H "X-API-Key: $SCAIVAULT_API_KEY"
|
| from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
pk = httpx.get(
"https://scaivault.scailabs.ai/api/v1/sign/keys/sign/acme/release-manifest/public-key",
headers={"X-API-Key": os.environ["SCAIVAULT_API_KEY"]},
).json()
public_key = Ed25519PublicKey.from_public_bytes(base64.b64decode(pk["public_key_b64"]))
public_key.verify(signature, b"release v2.4.0") # raises InvalidSignature if it doesn't match
|
| import { createPublicKey, verify } from "node:crypto";
const pk = await (await fetch(
"https://scaivault.scailabs.ai/api/v1/sign/keys/sign/acme/release-manifest/public-key",
{ headers: { "X-API-Key": process.env.SCAIVAULT_API_KEY! } },
)).json();
// Ed25519 public keys come raw; wrap them in an SPKI header for node:crypto.
const spki = Buffer.concat([Buffer.from("302a300506032b6570032100", "hex"), Buffer.from(pk.public_key_b64, "base64")]);
const ok = verify(null, Buffer.from("release v2.4.0"), createPublicKey({ key: spki, format: "der", type: "spki" }),
Buffer.from(signature_b64, "base64"));
|
The response carries version; add ?version=1 to fetch an older one. P-384 public keys already come as SubjectPublicKeyInfo DER, and ML-DSA-65 keys as raw bytes.
Sign many messages in one call
| curl -X POST https://scaivault.scailabs.ai/api/v1/sign/keys/sign/acme/release-manifest/batch-sign \
-H "X-API-Key: $SCAIVAULT_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"messages_b64\": [\"$(printf 'node-1' | base64)\", \"$(printf 'node-2' | base64)\"]}"
|
| messages = [b"node-1", b"node-2", b"node-3"]
resp = httpx.post(
"https://scaivault.scailabs.ai/api/v1/sign/keys/sign/acme/release-manifest/batch-sign",
headers={"X-API-Key": os.environ["SCAIVAULT_API_KEY"]},
json={"messages_b64": [base64.b64encode(m).decode() for m in messages]},
)
signatures = [base64.b64decode(s) for s in resp.json()["signatures_b64"]]
|
| const messages = ["node-1", "node-2", "node-3"];
const resp = await fetch(
"https://scaivault.scailabs.ai/api/v1/sign/keys/sign/acme/release-manifest/batch-sign",
{
method: "POST",
headers: { "X-API-Key": process.env.SCAIVAULT_API_KEY!, "Content-Type": "application/json" },
body: JSON.stringify({ messages_b64: messages.map((m) => Buffer.from(m).toString("base64")) }),
},
);
const { signatures_b64 } = await resp.json();
|
Signatures come back in the same order as the messages. A call takes up to 100 messages, and each one counts against the key's rate limit. Use this for mass renewals: one call signs far faster than a loop of single calls.
Sign a precomputed SHA-384 digest
P-384 keys (s2-ecdsa-p384) can sign a digest you computed yourself, so large payloads never cross the network. Send the 48-byte SHA-384 digest with prehashed_sha384:
| DIGEST=$(openssl dgst -sha384 -binary release.tar.gz | base64)
curl -X POST https://scaivault.scailabs.ai/api/v1/sign/keys/sign/acme/release-p384/sign \
-H "X-API-Key: $SCAIVAULT_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"message_b64\": \"$DIGEST\", \"prehashed_sha384\": true}"
|
| import hashlib
digest = hashlib.sha384(open("release.tar.gz", "rb").read()).digest()
resp = httpx.post(
"https://scaivault.scailabs.ai/api/v1/sign/keys/sign/acme/release-p384/sign",
headers={"X-API-Key": os.environ["SCAIVAULT_API_KEY"]},
json={"message_b64": base64.b64encode(digest).decode(), "prehashed_sha384": True},
)
|
| import { createHash } from "node:crypto";
import { readFileSync } from "node:fs";
const digest = createHash("sha384").update(readFileSync("release.tar.gz")).digest();
const resp = await fetch("https://scaivault.scailabs.ai/api/v1/sign/keys/sign/acme/release-p384/sign", {
method: "POST",
headers: { "X-API-Key": process.env.SCAIVAULT_API_KEY!, "Content-Type": "application/json" },
body: JSON.stringify({ message_b64: digest.toString("base64"), prehashed_sha384: true }),
});
|
The signature is the same one you'd get by sending the whole payload. prehashed_sha384 on any other suite, or a digest that isn't 48 bytes, returns 400 invalid_request.
Rotate a key
| curl -X POST https://scaivault.scailabs.ai/api/v1/sign/keys/sign/acme/release-manifest/rotate \
-H "X-API-Key: $SCAIVAULT_API_KEY"
|
| resp = httpx.post(
"https://scaivault.scailabs.ai/api/v1/sign/keys/sign/acme/release-manifest/rotate",
headers={"X-API-Key": os.environ["SCAIVAULT_API_KEY"]},
)
print(resp.json()["current_version"]) # 2
|
| const resp = await fetch(
"https://scaivault.scailabs.ai/api/v1/sign/keys/sign/acme/release-manifest/rotate",
{ method: "POST", headers: { "X-API-Key": process.env.SCAIVAULT_API_KEY! } },
);
console.log((await resp.json()).current_version); // 2
|
New signatures use version 2; signatures from version 1 still verify. Fetch the new public key and distribute it before verifiers need it.
Disable, enable or destroy a key
| KEY=https://scaivault.scailabs.ai/api/v1/sign/keys/sign/acme/release-manifest
curl -X POST "$KEY/disable" -H "X-API-Key: $SCAIVAULT_API_KEY" # stop signing, keep verifying
curl -X POST "$KEY/enable" -H "X-API-Key: $SCAIVAULT_API_KEY" # sign again
curl -X DELETE "$KEY" -H "X-API-Key: $SCAIVAULT_API_KEY" # permanent
|
| key = "https://scaivault.scailabs.ai/api/v1/sign/keys/sign/acme/release-manifest"
headers = {"X-API-Key": os.environ["SCAIVAULT_API_KEY"]}
httpx.post(f"{key}/disable", headers=headers)
httpx.post(f"{key}/enable", headers=headers)
httpx.delete(key, headers=headers) # permanent
|
| const key = "https://scaivault.scailabs.ai/api/v1/sign/keys/sign/acme/release-manifest";
const headers = { "X-API-Key": process.env.SCAIVAULT_API_KEY! };
await fetch(`${key}/disable`, { method: "POST", headers });
await fetch(`${key}/enable`, { method: "POST", headers });
await fetch(key, { method: "DELETE", headers }); // permanent
|
Destroying deletes the private key of every version and cannot be undone. The public keys stay, so old signatures still verify. Disable and enable need sign:manage; destroy needs sign:destroy, which you can keep away from the credentials your services use every day.
Restrict a service account to its own keys
Give the signing service its own role, limited by sign_path_prefixes to its key paths. This is an administrator task: it needs roles:write and service_accounts:write.
| curl -X POST https://scaivault.scailabs.ai/api/v1/roles \
-H "X-API-Key: $SCAIVAULT_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "release_signer", "scopes": ["sign:use", "sign:read"],
"constraints": {"sign_path_prefixes": ["sign/acme"]}}'
|
| resp = httpx.post(
"https://scaivault.scailabs.ai/api/v1/roles",
headers={"X-API-Key": os.environ["SCAIVAULT_ADMIN_KEY"]},
json={
"name": "release_signer",
"scopes": ["sign:use", "sign:read"],
"constraints": {"sign_path_prefixes": ["sign/acme"]},
},
)
|
| await fetch("https://scaivault.scailabs.ai/api/v1/roles", {
method: "POST",
headers: { "X-API-Key": process.env.SCAIVAULT_ADMIN_KEY!, "Content-Type": "application/json" },
body: JSON.stringify({
name: "release_signer",
scopes: ["sign:use", "sign:read"],
constraints: { sign_path_prefixes: ["sign/acme"] },
}),
});
|
Then create the service account with that role and issue its API key:
| SA=$(curl -s -X POST https://scaivault.scailabs.ai/api/v1/service-accounts \
-H "X-API-Key: $SCAIVAULT_ADMIN_KEY" -H "Content-Type: application/json" \
-d '{"name": "release-signer", "roles": ["release_signer"]}' | jq -r .id)
curl -X POST "https://scaivault.scailabs.ai/api/v1/service-accounts/$SA/keys" \
-H "X-API-Key: $SCAIVAULT_ADMIN_KEY" -H "Content-Type: application/json" \
-d '{"name": "ci"}'
|
The response's key is shown once; store it as the service's SCAIVAULT_API_KEY. That key can now sign with sign/acme/release-manifest and anything else under sign/acme, and nothing outside it:
| {
"detail": {
"error": {
"code": "access_denied",
"message": "signing key path 'sign/other/key' is not permitted for this credential; allowed prefixes: sign/acme"
}
}
}
|
Role names use lowercase letters, digits and underscores. A credential with several constrained roles may use the union of their prefixes.
What's next