> ## Documentation Index > Fetch the complete documentation index at: https://docs.cloudcruise.com/llms.txt > Use this file to discover all available pages before exploring further. # Create vault entry > Registers a new vault entry in the CloudCruise Platform. ## OpenAPI ````yaml vault-api/vault-api.yaml post /vault openapi: 3.1.0 info: title: CloudCruise Vault API version: 0.1.0 description: Endpoints for managing vault entries. servers: - url: https://api.cloudcruise.com description: CloudCruise Platform Production API Server security: - AuthScheme: [] paths: /vault: post: summary: Create vault entry description: Registers a new vault entry in the CloudCruise Platform. operationId: vault_post requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VaultEntryPayload' responses: '201': description: Vault entry successfully created content: application/json: schema: $ref: '#/components/schemas/VaultEntry' '400': description: |- Invalid request. Possible causes: - Missing or invalid authentication headers - Missing required fields (permissioned_user_id, domain) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: statusCode: 400 message: Invalid request error: Bad Request '401': description: >- Unauthorized. Possible causes: - Missing or invalid API key - No encryption key found for the workspace - Failed to decrypt provided credentials (user_name, password, or tfa_secret). Ensure your encryption method is up to date. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: statusCode: 401 message: >- Failed to decrypt password. Please ensure your encryption method is up to date as per https://docs.cloudcruise.com/vault error: Unauthorized '409': description: >- Conflict. A vault entry with the same permissioned_user_id and domain already exists in this workspace. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: statusCode: 409 message: >- A credential with this permissioned_user_id and domain already exists in this workspace error: Conflict '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: statusCode: 500 message: Internal server error error: Internal Server Error components: schemas: VaultEntryPayload: type: object additionalProperties: false title: Vault Entry Configuration description: >- Comprehensive vault entry configuration for a user. Supports multiple authentication methods and persistence options to maintain user sessions across workflow executions. Credentials have to be encrypted with your own encryption key prior to sending to the API. Learn more about how to encrypt credentials [here](https://docs.cloudcruise.com/concepts/vault). properties: id: type: string format: uuid description: >- Vault entry ID. Can be provided for updates to identify the entry to modify. permissioned_user_id: type: string description: >- Unique identifier for referencing this vault entry in workflow executions user_name: type: string nullable: true description: Primary encrypted username or email password: type: string nullable: true description: Encrypted password credential domain: type: string format: uri description: Target domain for vault entry credential (must be a valid URL) tfa_secret: type: string nullable: true description: >- Two-factor authenticator secret key (TOTP). Required when tfa_method is AUTHENTICATOR. This should be encrypted with your encryption key prior to sending to the API, similar to other credentials. The secret is typically provided in base32 format from authenticator apps. user_alias: type: string nullable: true description: A human readable identifier for the vault entry in the target system cookies: type: array nullable: true items: $ref: '#/components/schemas/Cookie' description: Cookies to set for this vault entry session_storage: type: object nullable: true description: Session storage data to set for this vault entry local_storage: type: object nullable: true description: Local storage data to set for this vault entry persist_session_storage: type: boolean nullable: true description: Whether to maintain session storage across workflow executions persist_local_storage: type: boolean nullable: true description: Whether to maintain local storage across workflow executions persist_cookies: type: boolean nullable: true description: Whether to maintain cookies across workflow executions skip_csrf_cookies: type: boolean nullable: true description: >- Whether to skip injecting CSRF-related cookies (e.g. XSRF-TOKEN) during session restore, allowing the server to generate fresh tokens cookie_domain_to_store: type: string format: uri nullable: true description: Specific domain to use when storing cookies allow_multiple_sessions: type: boolean nullable: true description: >- Controls whether the same set of credentials can be used simultaneously across multiple workflow executions. When set to true, multiple workflows can run in parallel using these credentials. When set to false or not specified, only one workflow can use these credentials at a time. We recommend keeping this as false (default) since some websites do not allow multiple active sessions for the same credentials and may invalidate existing sessions if a new one is detected. max_concurrency: type: integer minimum: 1 nullable: true description: >- Maximum number of concurrent sessions allowed when allow_multiple_sessions is true (null for unlimited) prevent_concurrency_during_login: type: boolean nullable: true description: >- Whether to prevent other sessions from starting while login is in progress expiry_time_from_last_use: type: string nullable: true description: >- Session expiry interval from last activity using PostgreSQL interval format (e.g., "01:30:00" for 1.5 hours) expiry_time_from_session_data_set: type: string nullable: true description: >- Session expiry interval from creation using PostgreSQL interval format (e.g., "7 days 00:00:00" for 7 days) tfa_method: type: string enum: - AUTHENTICATOR - EMAIL - MAGIC_LINK - SMS nullable: true description: >- Two-factor authentication method: - AUTHENTICATOR: Time-based one-time password using provided secret - EMAIL: TFA codes sent to CloudCruise email (info+{permissioned_user_id}+{site_identifier}@cloudcruise.com) - MAGIC_LINK: Magic login links sent to the CloudCruise email - SMS: TFA codes sent to CloudCruise phone (+1 415 753-4639) ip_address: type: string format: ipv4 nullable: true description: >- Legacy field for target IP address (deprecated, use proxy.target_ip instead) proxy: type: object properties: enable: type: boolean description: Whether to enable proxy for this vault entry target_ip: type: string format: ipv4 description: Target IP address to find the closest proxy for nullable: true description: >- Controls whether to use a proxy during browser agent runs with these credentials. If target_ip is provided, we will assign a proxy closest to that IP. proxy_setting: type: string enum: - random - static - country - custom nullable: true description: >- Proxy mode for this credential, overriding workflow-level proxy settings. - `random` / `static` / `country`: use CloudCruise's managed proxy pool. - `custom`: bring-your-own proxy — provide the URL in `proxy_value`. Requires the Enterprise `custom-proxy` entitlement. proxy_value: type: string nullable: true description: >- The proxy selector, interpreted according to `proxy_setting`. Not used for `random`. - `static`: the target IP address; CloudCruise picks the managed proxy closest to it. Send as plaintext. - `country`: the target country code, e.g. `US`. Send as plaintext. - `custom`: the proxy URL — `socks5://[user:pass@]host:port`, `http://[user:pass@]host:port`, or `https://[user:pass@]host:port`. This value (and only this mode's value) must be encrypted client-side with the workspace's AES-256 key before being sent, the same scheme as `password`; the API decrypts it to run SSRF validation, then re-encrypts it at rest. Private/loopback/link-local IPs, cloud metadata endpoints, internal suffixes, and hosts resolving to CloudCruise infrastructure are rejected. secret_provider_id: type: string format: uuid nullable: true description: >- Bind this entry to an external secret provider connection (e.g. 1Password) instead of storing credentials directly. When set, `user_name`, `password`, and the one-time-password seed are resolved live from the bound item at run time and should be left null. Must reference a connection in the same workspace. Obtain the id from `GET /secret-providers`. See the [1Password integration](https://docs.cloudcruise.com/integrations/1password). secret_ref: type: string nullable: true description: >- Reference to the specific item within the secret provider, in the form `op:///` for 1Password. Required when `secret_provider_id` is set. Obtain the value from the `ref` field of `GET /secret-providers/{id}/items`. secret_cache_ttl_seconds: type: integer minimum: 0 maximum: 86400 nullable: true description: >- Per-entry override for how long resolved secrets are cached before being re-fetched from the provider (0–86400 seconds; 0 = always live). Null uses the connection's default. One-time codes are always resolved live and never cached. required: - permissioned_user_id - domain VaultEntry: type: object description: Complete vault entry including system-generated fields properties: id: type: string format: uuid description: System-generated unique identifier for the vault entry permissioned_user_id: type: string description: >- Unique identifier for referencing this vault entry in workflow executions user_name: type: string nullable: true description: Encrypted username password: type: string nullable: true description: Encrypted password domain: type: string description: Target domain for vault entry credentials user_alias: type: string nullable: true description: Human readable identifier tfa_secret: type: string nullable: true description: >- Two-factor authenticator secret key (TOTP). Required when tfa_method is AUTHENTICATOR. This should be encrypted with your encryption key prior to sending to the API, similar to other credentials. The secret is typically provided in base32 format from authenticator apps. tfa_method: type: string enum: - AUTHENTICATOR - EMAIL - MAGIC_LINK - SMS nullable: true description: Two-factor authentication method tfa_email: type: string nullable: true description: >- Computed email address for TFA codes when tfa_method is EMAIL. CloudCruise generates this as info+{permissioned_user_id}+{site_identifier}@cloudcruise.com, where site_identifier is derived from the vault entry domain. This field is read-only and cannot be set via the API. tfa_phone_number: type: string nullable: true description: >- Computed phone number for TFA codes when tfa_method is SMS. This is automatically determined based on workspace configuration or defaults to CloudCruise's default phone number. This field is read-only and cannot be set via the API. workspace_id: type: string format: uuid description: The workspace this vault entry belongs to user_id: type: string format: uuid nullable: true description: The user who created this vault entry created_at: type: string format: date-time nullable: true description: Timestamp when the vault entry was created updated_at: type: string format: date-time nullable: true description: Timestamp when the vault entry was last updated session_storage: type: object nullable: true description: Session storage data default: {} local_storage: type: object nullable: true description: Local storage data default: {} cookies: type: array nullable: true items: $ref: '#/components/schemas/Cookie' description: Active vault entry cookies persist_local_storage: type: boolean description: Whether to maintain local storage across sessions persist_cookies: type: boolean description: Whether to maintain cookies across sessions persist_session_storage: type: boolean description: Whether to maintain session storage across sessions skip_csrf_cookies: type: boolean description: >- Whether to skip injecting CSRF-related cookies (e.g. XSRF-TOKEN) during session restore, allowing the server to generate fresh tokens cookie_domain_to_store: type: string nullable: true description: Specific domain to use when storing cookies allow_multiple_sessions: type: boolean description: Whether to allow multiple concurrent sessions max_concurrency: type: integer nullable: true description: Maximum number of concurrent sessions allowed (null for unlimited) prevent_concurrency_during_login: type: boolean nullable: true description: >- Whether to prevent other sessions from starting while login is in progress expiry_time_from_last_use: type: string nullable: true description: >- Session expiry interval from last activity (e.g., "01:30:00" for 1.5 hours). Set to null for no expiry from last use. expiry_time_from_session_data_set: type: string nullable: true description: >- Session expiry interval from creation (e.g., "7 days 00:00:00" for 7 days). Set to null for no expiry from session data set. effective_expires_at: type: string format: date-time nullable: true description: >- Computed timestamp when the session data expires based on expiry settings session_data_set_at: type: string format: date-time nullable: true description: Timestamp when the session data (cookies, storage) was last set ip_address: type: string nullable: true description: >- Legacy field for target IP address (deprecated, use proxy.target_ip instead) location: type: string nullable: true description: Geographic location associated with this vault entry proxy_string: type: string nullable: true description: >- The assigned proxy connection string for this vault entry. This is automatically assigned based on the proxy configuration provided when creating/updating the entry. Format: ip:port (e.g., "91.124.2.237:61234") proxy_setting: type: string enum: - random - static - country - custom nullable: true description: >- The proxy mode for this vault entry. - `random` / `static` / `country`: use CloudCruise's managed proxy pool. - `custom`: use the bring-your-own proxy URL stored in `proxy_value` (Enterprise only). proxy_value: type: string nullable: true description: >- The proxy selector for this entry, interpreted per `proxy_setting`. Not set for `random`. - `static`: the target IP address (plaintext). - `country`: the country code (plaintext). - `custom`: the bring-your-own proxy URL, returned encrypted with the workspace's AES-256 key (the same scheme as `password`). Decrypt it client-side with your key. secret_provider_id: type: string format: uuid nullable: true description: >- The external secret provider connection this entry is bound to (e.g. 1Password), or null for a directly-stored credential. When set, `user_name`/`password` are null and resolved live at run time. secret_ref: type: string nullable: true description: >- Reference to the bound item within the secret provider (e.g. `op:///` for 1Password). Null unless `secret_provider_id` is set. secret_cache_ttl_seconds: type: integer nullable: true description: >- Per-entry override for how long resolved secrets are cached (seconds), or null to use the connection default. ErrorResponse: type: object description: Error response returned when a request fails properties: statusCode: type: integer description: HTTP status code message: type: string description: Human-readable error message error: type: string description: HTTP status text (e.g., "Not Found", "Conflict") required: - statusCode - message Cookie: type: object description: >- Detailed cookie configuration for authentication persistence. Includes all standard cookie attributes and security settings. properties: name: type: string description: Cookie name/identifier value: type: string description: Cookie value/content domain: type: string description: Domain scope for the cookie path: type: string description: URL path scope for the cookie expirationDate: type: number format: float nullable: true description: Unix timestamp (in seconds) when the cookie expires httpOnly: type: boolean description: Restricts cookie access to HTTP(S) protocol only hostOnly: type: boolean description: Limits cookie to exact hostname matches only secure: type: boolean description: Requires HTTPS for cookie transmission session: type: boolean description: Indicates if this is a session cookie (cleared on browser close) storeId: type: string description: Browser cookie store identifier sameSite: type: string description: Cross-site request policy for the cookie required: - name - value - domain - path - httpOnly - hostOnly - secure - session - storeId - sameSite securitySchemes: AuthScheme: type: apiKey name: cc-key in: header description: >- API key-based authentication. Provide your CloudCruise API key in the cc-key header. ````