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

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.

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