---
title: Signing
path: api-guides/signing
status: published
---

# 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](../core-concepts/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
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
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
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
{
  "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
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
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
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
{
  "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
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
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
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
curl https://scaivault.scailabs.ai/api/v1/sign/keys/sign/acme/release-manifest/public-key \
  -H "X-API-Key: $SCAIVAULT_API_KEY"
```

```python
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
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
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
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
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
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
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
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
curl -X POST https://scaivault.scailabs.ai/api/v1/sign/keys/sign/acme/release-manifest/rotate \
  -H "X-API-Key: $SCAIVAULT_API_KEY"
```

```python
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
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
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
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
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
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
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
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
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
{
  "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

- [Signing reference](../reference/signing) — every endpoint, field and error code
- [Signing concepts](../core-concepts/signing) — suites, lifecycle, audit
- SDKs with signing built in: [Python](../sdks/python), [JavaScript](../sdks/javascript), [.NET](../sdks/dotnet), [Rust](../sdks/rust)
