> ## Documentation Index > Fetch the complete documentation index at: https://docs.ns.rocks/llms.txt > Use this file to discover all available pages before exploring further. # Mint certificate-backed OpenSSH relay access > Issues a short-lived OpenSSH user certificate for a caller-provided public key. The certificate is scoped to this machine, user, caller, and relay capabilities. The API credential may mint access but is not itself sufficient to log in to the relay; the OpenSSH client must prove possession of the matching private key. ## OpenAPI ````yaml /openapi.yaml post /v1/machines/{id}/ssh-access openapi: 3.1.0 info: title: Nullspace API version: 0.1.0 description: | Cloud machine platform for AI agents. Create on-demand microVMs, execute commands, manage files, automate desktop environments, and stream output over WebSocket. license: name: Apache-2.0 url: https://www.apache.org/licenses/LICENSE-2.0 servers: - url: https://api.13-215-85-171.sslip.io description: Private beta - url: https://nullspace.example description: Self-hosted single-host owned-domain - url: http://localhost description: Self-hosted single-host localhost/no-domain via Caddy - url: http://localhost:3000 description: Local development direct API security: - bearerAuth: [] tags: - name: Health description: Public process-liveness check (no auth required) - name: Machines description: Machine lifecycle, execution, and process management - name: Files description: Filesystem operations within a machine - name: Git description: First-class structured git operations within a machine - name: Desktop description: Desktop automation (mouse, keyboard, screenshots) - name: Recording description: Screen recording management - name: PTY description: Pseudo-terminal session management - name: Templates description: Machine template management - name: Agent Deployments description: Named, versioned agent deployment control plane - name: Volumes description: Persistent volume control plane and attached volume actions - name: WebSocket description: Streaming execution and PTY over WebSocket - name: Monitor description: In-repo WebSocket stream for machine health, metrics, and process updates - name: API Keys description: Runtime API key metadata and dormant self-serve key management - name: Account description: Dormant Supabase-session account profile, export, and deletion routes - name: Admin description: Supabase-session operator console APIs for account support - name: Auth description: Dormant self-serve Auth proxy routes gated by deployment config - name: Code description: Stateful code execution via Jupyter kernels (Code Interpreter) - name: Internal Operations description: Operator-only internal API surfaces; not part of the public SDK contract paths: /v1/machines/{id}/ssh-access: parameters: - $ref: '#/components/parameters/MachineId' post: tags: - Machines summary: Mint certificate-backed OpenSSH relay access description: | Issues a short-lived OpenSSH user certificate for a caller-provided public key. The certificate is scoped to this machine, user, caller, and relay capabilities. The API credential may mint access but is not itself sufficient to log in to the relay; the OpenSSH client must prove possession of the matching private key. operationId: createSshAccess requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SshAccessRequest' responses: '200': description: SSH access material and generated OpenSSH command content: application/json: schema: $ref: '#/components/schemas/SshAccessResponse' '400': $ref: '#/components/responses/InvalidRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/MachineNotFound' '503': $ref: '#/components/responses/FeatureUnavailable' components: parameters: MachineId: name: id in: path required: true schema: type: string description: Machine ID (e.g. mch_a1b2c3d4) schemas: SshAccessRequest: type: object required: - public_key properties: public_key: type: string description: OpenSSH public key to certify for relay login. example: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... user@example user: type: string description: Machine user to request in the certificate. default: root ttl_seconds: type: integer format: uint64 minimum: 1 maximum: 3600 description: Requested certificate lifetime in seconds. expires_in_minutes: type: integer format: uint64 minimum: 1 maximum: 60 description: SDK-compatible requested certificate lifetime in minutes. SshAccessResponse: type: object required: - certificate - host - port - user - expires_at - access_id - command properties: certificate: type: string description: OpenSSH user certificate for the submitted public key. host: type: string description: Public SSH relay hostname. example: ssh.nullspace.io port: type: integer format: uint16 description: Public SSH relay port. example: 22 user: type: string description: Machine user encoded as a certificate principal. example: root expires_at: type: string format: date-time description: Certificate expiration time. access_id: type: string description: Revocable access grant identifier. Treat as sensitive in logs. command: type: string description: Best-effort OpenSSH command for manual use. host_key: type: string nullable: true description: Relay host public key for known_hosts pinning when configured. ErrorResponse: type: object required: - error - code properties: error: type: string description: Human-readable error message code: type: string description: Machine-readable error code enum: - invalid_request - machine_not_found - snapshot_not_found - template_not_found - template_build_not_found - template_name_claim_not_found - machine_not_ready - unauthorized - auth_failed - auth_locked - auth_proxy_error - auth_proxy_unavailable - invalid_auth_redirect - invalid_oauth_provider - captcha_required - captcha_failed - captcha_unavailable - disposable_email - signup_rate_limited - oauth_rate_limited - email_action_rate_limited - database_error - email_not_verified - account_deleted - operator_required - account_not_found - account_not_soft_deleted - account_hard_delete_active_resources - file_upload_error - build_error - exec_timeout - exec_failed - file_error - not_implemented - capacity_exceeded - QUOTA_EXCEEDED - feature_unavailable - snapshot_in_use - no_eligible_runtime_host - same_host_required - incompatible_snapshot - rebuild_required - rate_limit_exceeded - transition_in_progress - transition_conflict - agent_deployment_not_found - agent_deployment_version_not_found - agent_run_not_found - agent_service_instance_not_found - agent_deployment_name_conflict - agent_deployment_idempotency_mismatch - agent_deployment_invalid_config - agent_deployment_invalid_state - volume_beta_restriction - volume_invalid_mount_path - volume_overlapping_mounts - volume_backend_capability_unsupported - volume_quota_exceeded - volume_mount_credential_issue_failed - volume_backend_unavailable - volume_stale_revision - volume_busy - volume_read_only - volume_limit_exceeded - internal_error error_detail: $ref: '#/components/schemas/ErrorDetail' request_id: type: string description: Request correlation ID returned in the `x-request-id` header build_id: type: string description: Template build ID when the error is associated with a tracked build ErrorDetail: oneOf: - $ref: '#/components/schemas/TemplateFailureDetail' - $ref: '#/components/schemas/UploadFailureDetail' TemplateFailureDetail: type: object required: - code - message - phase - retryable - suggested_action properties: code: type: string enum: - unauthorized - file_upload_error - build_error - internal_error message: type: string phase: $ref: '#/components/schemas/TemplateFailurePhase' retryable: type: boolean suggested_action: type: string step_index: type: integer attempt: type: integer max_attempts: type: integer cache_subject: type: string build_id: type: string request_id: type: string description: >- Present on terminal request-originated failures and blocking error responses. details: type: object additionalProperties: true description: >- Stable failure metadata. Includes a `reason` key plus phase-specific fields such as `blob_id`, `path`, digest/size mismatch values, `command`, or `alias`. UploadFailureDetail: type: object required: - reason - message - retryable properties: reason: $ref: '#/components/schemas/UploadFailureReason' message: type: string retryable: type: boolean upload_id: type: string request_id: type: string path: type: string description: >- Normalized absolute machine path associated with the failed upload when available. part_number: type: integer format: uint32 details: type: object additionalProperties: true description: >- Additional failure diagnostics; keys depend on the failure reason, deliberately open. TemplateFailurePhase: type: string enum: - auth - preflight - blob_upload - prepare - build_step - readiness - snapshot - finalize - interrupted UploadFailureReason: type: string enum: - insufficient_staging_space - size_limit_exceeded - invalid_part_checksum - part_out_of_range - part_size_mismatch - whole_checksum_mismatch - upload_expired - upload_aborted - upload_already_completed - target_conflict - directory_extract_invalid_path - directory_extract_invalid_symlink - directory_extract_unsupported_entry - missing_parts responses: InvalidRequest: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: Missing or invalid bearer credential content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: summary: Missing or invalid bearer credential value: error: Missing or invalid bearer credential code: unauthorized request_id: req_123 MachineNotFound: description: Machine not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' FeatureUnavailable: description: Feature is unavailable in current deployment mode content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: bearerAuth: type: http scheme: bearer description: API key passed as Bearer token ````