---
title: Signing
path: reference/signing
status: published
---

# Signing Reference

Endpoint reference for the signing engine: non-exportable keys that sign raw bytes. For a walkthrough, see the [Signing guide](../api-guides/signing). For the model, see [Signing](../core-concepts/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](#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](#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](#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](#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](./authentication#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](../api-guides/signing)
- [Signing (Concepts)](../core-concepts/signing)
- [Authentication](./authentication) — scopes and resource constraints
