Platform
ScaiWave ScaiGrid ScaiCore ScaiBot ScaiDrive ScaiKey Models Tools & Services
Solutions
Organisations Developers Internet Service Providers Managed Service Providers AI-in-a-Box
Resources
Support Documentation Blog Downloads
Company
About Research Careers Investment Opportunities Contact
Log in

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#

bash
1
2
3
4
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"}'
python
1
2
3
4
5
6
7
8
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"])
typescript
1
2
3
4
5
6
7
8
9
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):

json
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "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#

bash
1
2
3
4
5
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)
python
1
2
3
4
5
6
7
8
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"])
typescript
1
2
3
4
5
6
7
8
9
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:

json
1
2
3
4
5
6
{
  "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:

bash
1
2
3
4
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\"}"
python
1
2
3
4
5
6
7
8
9
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}
typescript
1
2
3
4
5
6
7
8
9
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:

bash
1
2
curl https://scaivault.scailabs.ai/api/v1/sign/keys/sign/acme/release-manifest/public-key \
  -H "X-API-Key: $SCAIVAULT_API_KEY"
python
1
2
3
4
5
6
7
8
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
typescript
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
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#

bash
1
2
3
4
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)\"]}"
python
1
2
3
4
5
6
7
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"]]
typescript
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
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:

bash
1
2
3
4
5
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}"
python
1
2
3
4
5
6
7
8
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},
)
typescript
1
2
3
4
5
6
7
8
9
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#

bash
1
2
curl -X POST https://scaivault.scailabs.ai/api/v1/sign/keys/sign/acme/release-manifest/rotate \
  -H "X-API-Key: $SCAIVAULT_API_KEY"
python
1
2
3
4
5
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
typescript
1
2
3
4
5
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#

bash
1
2
3
4
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
python
1
2
3
4
5
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
typescript
1
2
3
4
5
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.

bash
1
2
3
4
5
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"]}}'
python
1
2
3
4
5
6
7
8
9
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"]},
    },
)
typescript
1
2
3
4
5
6
7
8
9
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:

bash
1
2
3
4
5
6
7
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:

json
1
2
3
4
5
6
7
8
{
  "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#

Updated 2026-11-09 00:55:29 View source (.md) rev 3