Signing
Endpoint reference for the signing engine: non-exportable keys that sign raw bytes. For a walkthrough, see the Signing guide. For the model, see Signing.
Base path: /api/v1/sign/
{path} is the key's path exactly as created, slashes included — for example /api/v1/sign/keys/sign/acme/release-manifest/sign. Don't URL-encode the slashes. All bytes (messages, signatures, public keys) are standard base64. The API doesn't redirect: a path with a trailing slash returns 404.
Keys#
POST /api/v1/sign/keys#
Create a key. The private key is generated inside ScaiVault and never returned.
Body:
| Field | Required | Description |
|---|---|---|
path |
Yes | Key path, unique per tenant; may contain / |
suite |
Yes | s3-ed25519, s2-ecdsa-p384 or s4-mldsa65. Fixed for the key's life |
name |
No | Display name |
description |
No | |
rate_limit_per_min |
No | Signatures per minute for this key (≥ 1). No limit when absent |
hsm_backed |
No | Reserved. true is rejected with 409 signing_key_unavailable until HSM-backed keys are available |
Response 201: a SigningKey.
Scope: sign:create.
GET /api/v1/sign/keys#
List the tenant's keys. A credential with a sign_path_prefixes constraint sees only keys under its prefixes.
Response: array of SigningKey.
Scope: sign:read.
GET /api/v1/sign/keys/{path}/public-key#
Query: version (optional, default the current version).
Response:
| Field | Description |
|---|---|
key_id |
|
version |
Version this public key belongs to |
suite |
|
public_key_b64 |
Ed25519 and ML-DSA-65: raw key. P-384: SubjectPublicKeyInfo DER |
Public keys stay available after a key is disabled or destroyed.
Scope: sign:read.
POST /api/v1/sign/keys/{path}/sign#
Sign with the key's current version.
Body:
| Field | Required | Description |
|---|---|---|
message_b64 |
Yes | The bytes to sign |
prehashed_sha384 |
No | Default false. s2-ecdsa-p384 only: message_b64 is a 48-byte SHA-384 digest |
Response: key_id, version, suite, signature_b64.
Counts 1 against the key's rate limit.
Scope: sign:use.
POST /api/v1/sign/keys/{path}/batch-sign#
Sign several messages with the current version in one call.
Body:
| Field | Required | Description |
|---|---|---|
messages_b64 |
Yes | Up to 100 messages |
prehashed_sha384 |
No | As for sign; applies to every message |
Response: key_id, version, suite, signatures_b64 (same order as messages_b64).
Counts one unit per message against the key's rate limit; a batch that doesn't fit is refused whole.
Scope: sign:use.
POST /api/v1/sign/keys/{path}/verify#
Body:
| Field | Required | Description |
|---|---|---|
message_b64 |
Yes | |
signature_b64 |
Yes | |
version |
No | Accept only this version. Default: try every version, newest first |
prehashed_sha384 |
No | s2-ecdsa-p384: message_b64 is the 48-byte digest that was signed. Ignored for other suites |
Response: valid (boolean), matched_version (the version that verified, or null).
An invalid signature returns 200 with "valid": false.
Scope: sign:read.
POST /api/v1/sign/keys/{path}/rotate#
Create a new version and make it the signer. Earlier versions keep verifying. Active keys only.
Response: SigningKey with the new current_version.
Scope: sign:manage.
POST /api/v1/sign/keys/{path}/disable#
Stop signing; verification and public-key reads continue.
Scope: sign:manage.
POST /api/v1/sign/keys/{path}/enable#
Allow signing again after disable.
Scope: sign:manage.
DELETE /api/v1/sign/keys/{path}#
Destroy the key: delete the private part of every version. Permanent. Public keys are kept, so earlier signatures still verify.
Response: SigningKey with status: "destroyed".
Scope: sign:destroy. It is separate from sign:manage because destroying can't be undone; keep it off day-to-day credentials.
SigningKey#
| Field | Description |
|---|---|
id |
sk_… |
path |
|
name |
|
suite |
s3-ed25519, s2-ecdsa-p384 or s4-mldsa65 |
status |
active, disabled or destroyed |
current_version |
Version that signs |
hsm_backed |
Always false for now |
rate_limit_per_min |
null when unlimited |
No response ever contains private key material.
Access constraints#
A role can carry "constraints": {"sign_path_prefixes": ["sign/acme"]} (see Roles and resource constraints). A credential holding such a role may create, list, use and manage only keys at or under those prefixes, matched per path segment. Other paths return 403 access_denied.
Errors#
Errors use the standard body, {"detail": {"error": {"code", "message", "details"}}}.
| Status | Code | When |
|---|---|---|
| 400 | invalid_request |
prehashed_sha384 on a suite other than s2-ecdsa-p384, or a digest that isn't 48 bytes |
| 401 | authentication_required |
No or invalid credential |
| 403 | insufficient_scope |
Credential lacks the operation's sign:* scope |
| 403 | access_denied |
Key path is outside the credential's sign_path_prefixes |
| 404 | signing_key_not_found |
No key at that path in your tenant |
| 409 | signing_key_exists |
POST /api/v1/sign/keys for a path that's taken |
| 409 | signing_key_unavailable |
Key is disabled or destroyed, rotate on a non-active key, or hsm_backed: true |
| 422 | validation_error |
Bad base64, unknown suite, more than 100 messages |
| 429 | rate_limited |
Key's rate_limit_per_min exceeded. Sends Retry-After |
Audit actions#
| Action | Written |
|---|---|
sign.sign |
Per message signed: caller, time, SHA-256 of the message, key, version, suite. In the background |
sign.key.create, sign.key.rotate, sign.key.disable, sign.key.enable, sign.key.destroy |
In the same transaction as the change |
Resource type: signing_key.
Related#
- Signing guide
- Signing (Concepts)
- Authentication — scopes and resource constraints