Manage SSH Key

Overview

The SSH Key Download API allows authenticated users to download the SSH private key associated with their Dataoorts account.

This endpoint returns the private key as a downloadable file rather than a JSON response. It can be used to securely retrieve the key for SSH-based access to supported instances and infrastructure resources.

For successful requests, the response contains the SSH key file. If a request fails, the API may return a JSON error response containing information about the failure.

Important: SSH private keys are sensitive credentials. Store downloaded keys securely and never share them or expose them in public repositories, logs, or client-side applications.

Endpoint

Property	Value
HTTP Method	`GET`
Endpoint	`/download/ssh_key`
Full URL	`https://cloud.dataoorts.com/api/v1/download/ssh_key`
Authentication	Bearer Token
Successful Response	Downloadable Object
Error Response	May contain JSON

Authentication

A valid Dataoorts Unify API key is required to access this endpoint.

Include the API key in the Authorization header using the Bearer authentication scheme.

Authorization: Bearer YOUR_API_KEY

You can generate or manage your API key through the Dataoorts Unify API.

Keep your API key confidential and avoid embedding it directly in public source code.

Request Examples

Use cURL to download the SSH private key to a local file:

curl --request GET \
  --url "https://cloud.dataoorts.com/api/v1/download/ssh_key" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --fail \
  --show-error \
  --output temporary.pem

Replace YOUR_API_KEY with your actual Dataoorts API key.

The command saves the downloaded file as temporary.pem in the current working directory. The filename is local to your download command and does not necessarily reflect the filename returned by the server.

On Linux or macOS, restrict access to the downloaded key:

chmod 600 temporary.pem

This limits file access to the file owner under standard Unix permission rules.

Python Example

import os
from pathlib import Path

import requests


API_BASE_URL = "https://cloud.dataoorts.com/api/v1"


def download_ssh_key(
    api_key: str,
    save_path: str = "temporary.pem",
) -> Path:
    """
    Download the SSH private key associated with a Dataoorts account.

    Args:
        api_key: Your Dataoorts Unify API key.
        save_path: Local path where the downloaded key will be saved.

    Returns:
        Path: The path to the downloaded SSH key file.

    Raises:
        RuntimeError: If the API returns an error or an unexpected JSON
                      response instead of the key file.
        requests.exceptions.RequestException:
            If the HTTP request fails.
    """
    url = f"{API_BASE_URL}/download/ssh_key"

    headers = {
        "Authorization": f"Bearer {api_key}",
        "Accept": "*/*",
    }

    destination = Path(save_path)

    with requests.get(
        url,
        headers=headers,
        timeout=30,
        stream=True,
    ) as response:

        if not response.ok:
            try:
                error_data = response.json()
                message = error_data.get(
                    "message",
                    "The API request failed.",
                )
            except ValueError:
                message = response.text[:1000] or "No error details provided."

            raise RuntimeError(
                f"SSH key download failed "
                f"(HTTP {response.status_code}): {message}"
            )

        content_type = response.headers.get(
            "Content-Type", ""
        ).lower()

        if "application/json" in content_type:
            raise RuntimeError(
                "The API returned JSON instead of an SSH key file. "
                "Check the API response and your account access."
            )

        with destination.open("wb") as file:
            for chunk in response.iter_content(chunk_size=8192):
                if chunk:
                    file.write(chunk)

    # Restrict permissions on systems that support Unix file permissions.
    if os.name == "posix":
        destination.chmod(0o600)

    return destination


if __name__ == "__main__":
    api_key = os.getenv("DATAOORTS_API_KEY")

    if not api_key:
        raise RuntimeError(
            "Set the DATAOORTS_API_KEY environment variable first."
        )

    try:
        key_path = download_ssh_key(
            api_key=api_key,
            save_path="temporary.pem",
        )

        print(f"SSH key downloaded successfully: {key_path.resolve()}")

    except requests.exceptions.RequestException as exc:
        print(f"Network or HTTP request error: {exc}.")

    except RuntimeError as exc:
        print(f"API error: {exc}.")

Set your API key as an environment variable before running the script.

Linux / macOS

export DATAOORTS_API_KEY="YOUR_API_KEY"
python download_ssh_key.py

Windows PowerShell

$env:DATAOORTS_API_KEY="YOUR_API_KEY"
python download_ssh_key.py

The downloaded key will be saved to temporary.pem in the current working directory. You can specify a different destination using the save_path argument.

Successful Response Example

A successful request returns the SSH private key file directly in the HTTP response body.

The response is not a JSON object. The returned content should be saved as a file rather than parsed using a JSON decoder.

Property	Description
HTTP Status	`200 OK`
Response Body	SSH private key file contents
Content Type	File response; the exact media type depends on the server response
Filename	May be provided through the `Content-Disposition` response header

Actual key contents are intentionally not shown in this doc because private keys are sensitive credentials.

Error Responses

When the request fails, the API may return a JSON error response instead of a private key file.

Applications should inspect the HTTP status code and, when appropriate, parse the JSON error body to identify the problem. Do not save an error response as an SSH private key.

For example, an error response might contain a message in the following format:

{
  "status": "error",
  "message": "Request could not be completed."
}

This is an illustrative example only; the actual error structure and message depend on the API response.

Security Best Practices

Protect your API key: Do not expose your Bearer token in public repositories, browser-side code, or application logs.
Secure the downloaded file: Restrict filesystem permissions and store the private key in a trusted location.
Avoid unnecessary copies: Do not distribute the private key or keep unnecessary duplicates.
Handle errors safely: Check the HTTP response before treating the downloaded content as a valid key file.
Use secure storage: Remove temporary copies when they are no longer needed, in accordance with your security requirements.

Get Help and Support

For assistance with SSH key downloads, API authentication, or unexpected responses, contact the Dataoorts support team.

Support Email: [email protected]