ONEKEY Python client

The official Python client handles authentication, firmware uploads, and analysis result retrieval with simple commands.

Installation

Install from PyPI:

pip install onekey-client

Or from the GitHub repository:

pip install git+https://github.com/onekey-sec/python-client.git

Basic usage

The client provides the onekey command with various subcommands:

onekey [OPTIONS] COMMAND [ARGS]...

Authentication

Authenticate using either email/password credentials or API tokens.

Email and passwordAPI tokens

Provide credentials via environment variables (recommended) or command line options:

# Environment variables (recommended)
export ONEKEY_EMAIL="your-email@example.com"
export ONEKEY_PASSWORD="your-password"
export ONEKEY_TENANT_NAME="your-tenant"

# Run commands
onekey list-tenants

# Command line options
onekey \
  --email "your-email@example.com" \
  --password "your-password" \
  --tenant "your-tenant" \
  list-tenants

Use an API token for automation and CI/CD workflows:

# Set token as environment variable
export ONEKEY_TOKEN="your-api-token"
export ONEKEY_TENANT_NAME="your-tenant"

# Run commands
onekey list-tenants

Tip

For CI/CD pipelines and automated scripts, use API tokens instead of email/password. Tokens provide better security through scoped permissions and don't require storing user credentials.

Global options

Option	Description	Required	Default
--email TEXT	Email address for authentication		-
--password TEXT	Password for authentication		-
--tenant TEXT	Tenant name		-
--api-url TEXT	API endpoint URL		https://app.eu.onekey.com/api
--token TEXT	API token (alternative to email/password)		-
--disable-tls-verify	Disable TLS certificate verification testing only		false
--help	Show help message		-

Commands

list-tenants

List all tenants accessible with your credentials:

onekey list-tenants

Output:

Available tenants:
- my-company
- my-company-dev
- partner-tenant

get-tenant-token

Obtain a Bearer token for direct API access:

onekey get-tenant-token

Output:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

You can use this token in API requests:

curl -H "Authorization: Bearer $(onekey get-tenant-token)" \
  https://app.eu.onekey.com/api/graphql

upload-firmware

Upload firmware to the platform for analysis:

onekey upload-firmware [OPTIONS] FIRMWARE_FILE

Options:

Option	Description	Required	Default
--product TEXT	Product name		-
--vendor TEXT	Vendor name		-
--version TEXT	Firmware version		-
--name TEXT	Custom firmware name		Auto-generated
--product-group TEXT	Product group name		"Default"
--analysis-configuration TEXT	Analysis configuration name		"Default"

If no custom firmware is specified with the --name option the client auto-generates one based on Product and Vendor name.

Example:

onekey upload-firmware \
  --product "IoT Gateway" \
  --vendor "ACME Corp" \
  --version "2.1.0" \
  firmware.bin

Output:

660e8400-e29b-41d4-a716-446655440001

The command returns a Firmware ID (UUID) that uniquely identifies your uploaded firmware. Save this ID – you'll need it to check analysis status, retrieve results, and perform any further operations on this firmware.

Info

• Use consistent product names across firmware versions to enable comparison.
• You must have Upload permission for the target product group. See Permissions for details.
• The --analysis-configuration option selects which analysis configuration to use. Use "Default" for standard analysis or – if you've created one on the platform – specify the custom configuration.

ci-result

Once the analysis is completed, retrieve the results:

onekey ci-result [OPTIONS]

Options:

Option	Description	Required	Default
--firmware-id UUID	Firmware UUID (from upload)		-
--check-interval INTEGER	Seconds between analysis status checks		60
--retry-count INTEGER	Max retries on communication errors		10
--retry-wait INTEGER	Seconds between retries		60
--exit-code-on-new-finding INTEGER	Exit code when new issues found		1
--junit-path PATH	Export JUnit XML report		-

Example:

onekey ci-result --firmware-id 660e8400-e29b-41d4-a716-446655440001

Output:

Waiting for analysis to finish on firmware: 660e8400-e29b-41d4-a716-446655440001
Firmware analysis finished successfully, results: https://app.eu.onekey.com/firmwares?firmwareId=660e8400-e29b-41d4-a716-446655440001
Previous firmware results: https://app.eu.onekey.com/firmwares?firmwareId=550e8400-e29b-41d4-a716-446655440000
################################################################################
New / dropped issue count: 2 / 0
New / dropped CVE count: 1 / 0

New Issues:
- [HIGH] Insecure cryptographic function: MD5 hash usage detected
- [MEDIUM] Hardcoded credentials found in configuration

New CVEs:
- CVE-2024-1234: Buffer overflow in HTTP server (CVSS: 8.1)

The command:

1. Polls the firmware analysis status via GraphQL queries.
2. Locates the previous firmware upload for the same product.
3. Compares analysis results to identify new and resolved findings.
4. Optionally generates a JUnit .xml report for CI/CD integration.
5. Exits with configurable status code if new findings are detected.

Complete workflow example

Upload and analyze firmware in one script:

#!/bin/bash
set -e

# Upload firmware
FIRMWARE_ID=$(onekey upload-firmware \
  --product "MyDevice" \
  --vendor "MyCompany" \
  --version "1.0" \
  firmware.bin)

echo "Uploaded firmware: $FIRMWARE_ID"

# Wait for analysis and check results
onekey ci-result \
  --firmware-id "$FIRMWARE_ID" \
  --junit-path ./test-results/security.xml \
  --exit-code-on-new-finding 1

echo "Analysis passed - no new security findings"