# Create vault

Create a vault and request acceptance from its signers. Check the vault status while waiting for their responses. Registered signers may be selected even when offline; unregistered signers cannot participate.
Reuse the same Idempotency-Key with the same parameters when retrying this request. Current access is checked on every retry. The original successful response is available for 24 hours from successful completion; replay does not repeat the action. Concurrent requests with the same key return 409 idempotency_in_progress, changed parameters return idempotency_request_mismatch, and expired replay returns idempotency_result_expired. Missing, invalid or repeated headers return 400.

Endpoint: POST /vaults
Version: 1.0.0
Security: Auth

## Security:

  - `Auth` (unknown)
    apiKey in header X-Api-Key scopes: vks:access

## Header parameters:

  - `Idempotency-Key` (string, required)
    Case-sensitive opaque key for one mutation intent. Send exactly one header occurrence containing 1 to 128 visible ASCII bytes (0x21..0x7e). Commas are literal data; do not trim, lowercase or require UUID syntax. Reuse the same key for retries, with current authorization checked on every attempt. Repeated header occurrences are rejected.

## Request fields (application/json):

  - `label` (string, required)
    Display name for the vault.

  - `required_signer_ids` (array, required)
    Signers that must take part in every transaction. The required and additional lists may contain at most five signers in total. Leave empty if no individual signer is mandatory.

  - `additional_signer_ids` (array, required)
    Signers that can complete the group alongside the required signers. The required and additional lists may contain at most five signers in total. Leave empty when all signers are required.

  - `threshold_k` (integer, required)
    Number of additional signers needed alongside all required signers. Use zero when there are no additional signers; otherwise select at least one, up to the size of that list. Every signing group must contain at least two signers.

## Request examples:

  - `Any two of three signers may approve a transaction` (unknown)
    Replace the example identifiers with registered signers.

  - `One mandatory signer and either of two additional signers` (unknown)
    Replace the example identifiers with registered signers.

## Response 201:

  - `201` (unknown)
    The vault, awaiting signer acceptance.

## Response 201 fields (application/json):

  - `item` (object, required)
    A group of signers and the approval rules for the accounts they control.

  - `item.vault_id` (string, required)
    Unique identifier of the vault.

  - `item.state` (string, required)
    Vault acceptance status. An active vault is ready for account creation.
    Enum: "awaiting_acceptance", "active", "rejected", "expired", "aborted"

  - `item.label` (string, required)
    Display name chosen for the vault.

  - `item.participants` (array, required)
    Signers invited to participate in the vault and their acceptance status.

  - `item.participants.signer_id` (string, required)
    Unique identifier of the signer.

  - `item.participants.name` (string, required)
    Name provided by the signer. Empty if the name is unavailable or already used by another signer.

  - `item.participants.required` (boolean, required)
    Whether this signer must take part in every transaction.

  - `item.participants.identity_fingerprint` (string, required)
    SHA-256 fingerprint of the decoded public key bytes. Use it to compare and verify the key.

  - `item.participants.accepted` (boolean, required)
    Whether the signer has accepted the vault configuration.

  - `item.access_rule` (object, required)
    Rules for choosing the signers needed to approve and sign a transaction.

  - `item.access_rule.required_signer_ids` (array, required)
    Signers that must take part in every transaction. The required and additional lists may contain at most five signers in total.

  - `item.access_rule.additional_signer_ids` (array, required)
    Signers that can complete the group alongside the required signers. The required and additional lists may contain at most five signers in total.

  - `item.access_rule.threshold_k` (integer, required)
    Number of additional signers needed alongside all required signers.

  - `item.minimal_quorums` (array, required)
    Available signing groups. Choose one complete group when creating a transaction.

  - `item.vault_hash` (string, required)
    Hash used to verify the vault configuration.

  - `item.created_at` (string, required)
    Time the vault was created.

  - `item.expires_at` (string, required)
    Deadline for the signers to accept the vault.

## Response 400:

  - `400` (unknown)
    Some request values are missing or invalid. Check fields for details.

## Response 400 fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
    Example: https://docs.vilna.io/apis/errors#internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad Request

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /traces/0123456789abcdef0123456789abcdef

  - `code` (string, required)
    Stable machine-readable error code for programmatic error handling. Unlike the HTTP `status` or free-form `detail`, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to `unspecified` when the server has not assigned a specific code.
    Example: blockchain.not_found

  - `fields` (array)
    List of invalid fields in the request.

  - `fields.name` (string, required)
    The name of the invalid field.
    Example: max_len

  - `fields.reason` (string, required)
    Why this field is invalid.
    Example: 32

## Response 401:

  - `401` (unknown)
    Authentication is required to make this request.

## Response 401 fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
    Example: https://docs.vilna.io/apis/errors#internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad Request

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /traces/0123456789abcdef0123456789abcdef

  - `code` (string, required)
    Stable machine-readable error code for programmatic error handling. Unlike the HTTP `status` or free-form `detail`, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to `unspecified` when the server has not assigned a specific code.
    Example: blockchain.not_found

## Response 403:

  - `403` (unknown)
    You do not have permission to access VKS in this workspace.

## Response 403 fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
    Example: https://docs.vilna.io/apis/errors#internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad Request

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /traces/0123456789abcdef0123456789abcdef

  - `code` (string, required)
    Stable machine-readable error code for programmatic error handling. Unlike the HTTP `status` or free-form `detail`, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to `unspecified` when the server has not assigned a specific code.
    Example: blockchain.not_found

## Response 409:

  - `409` (unknown)
    The request conflicts with the current resource state.

## Response 409 fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
    Example: https://docs.vilna.io/apis/errors#internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad Request

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /traces/0123456789abcdef0123456789abcdef

  - `code` (string, required)
    Stable machine-readable error code for programmatic error handling. Unlike the HTTP `status` or free-form `detail`, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to `unspecified` when the server has not assigned a specific code.
    Example: blockchain.not_found

## Response 503:

  - `503` (unknown)
    The service is temporarily unavailable. Try again later.

## Response 503 fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
    Example: https://docs.vilna.io/apis/errors#internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad Request

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /traces/0123456789abcdef0123456789abcdef

  - `code` (string, required)
    Stable machine-readable error code for programmatic error handling. Unlike the HTTP `status` or free-form `detail`, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to `unspecified` when the server has not assigned a specific code.
    Example: blockchain.not_found

## Response default:

  - `default` (unknown)
    Details of an error that prevented the request from completing.

## Response default fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
    Example: https://docs.vilna.io/apis/errors#internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad Request

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /traces/0123456789abcdef0123456789abcdef

  - `code` (string, required)
    Stable machine-readable error code for programmatic error handling. Unlike the HTTP `status` or free-form `detail`, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to `unspecified` when the server has not assigned a specific code.
    Example: blockchain.not_found

## Response 400 examples:

  - `Invalid request` (unknown)

## Response 409 examples:

  - `Account is not ready to sign transactions` (unknown)

  - `Transaction state does not allow this operation` (unknown)

  - `Another send is in progress` (unknown)

  - `Transaction already accepted` (unknown)

## Response default examples:

  - `Unexpected failure` (unknown)