Skip to content

API and SDKs

Every Deployport surface calls the same HTTP API. The console, the CLI and the desktop app each carry a client generated from the API definition, so an operation added to the API is an operation all three call.

The API is regional, one host per region:

RegionBase URL
us-east-2https://machinery.us-east-2.api.deployport.io/api
us-west-2https://machinery.us-west-2.api.deployport.io/api

An operation’s path is <Resource>/<Operation>, for example Machine/Get or Machine/List.

Call the region that serves the machine. A machine’s authority region is the one that answers its check-ins and keeps its metrics history, and deployport config set-region <region> sets the region the CLI calls.

A caller signs every request with an IAM access key and a secret. deployport login writes that pair to ~/.deployport/credentials.yml, and a program can read it from the environment instead:

VariableWhat it carries
DEPLOYPORT_ACCESS_KEY_IDthe access key id
DEPLOYPORT_SECRET_ACCESS_KEYthe secret
DEPLOYPORT_REGIONthe region to call

A signed request carries the vendor headers X-Dpp-Date, X-Dpp-Service, X-Dpp-Resource, X-Dpp-Operation, X-Dpp-Content-Sha256 and X-Dpp-Region, and its Authorization header names the scheme, the credential, the signed headers and the signature:

Authorization: DPP1-HMAC-SHA256 Credential=<access-key-id>/<date>/<region>/machinery/dpp1_request, SignedHeaders=host;x-dpp-content-sha256;x-dpp-date;x-dpp-operation;x-dpp-region;x-dpp-resource;x-dpp-service, Signature=<hex>

The signature covers those headers, the host, the body digest and the operation, and the signing key is derived from the secret by an HMAC chain over the date, the region, the service and the request code. This page names the scheme; the generated clients are its reference implementation, and Where the clients live says which one to read.

Every operation asserts an IAM action over a resource, and the action names the resource it is scoped over:

ActionScoped over
machinery:GetMachinemachinery:Machine(<machine-id>)
machinery:CreateMachinemachinery:Account(*), and machinery:WorkerPool(<worker-pool-id>) when the launch names a worker pool
machinery:RunCommandmachinery:Machine(<machine-id>)

A key with no policy attached reaches nothing. Write a policy covers the document, and Run a command on a machine names the actions one operation needs as a worked example.

The clients are generated from the service’s own API definition, and each one ships inside the tool that uses it rather than as a package of its own:

ClientLanguageWhere it lives
CLIGothe deployport binary, built from sdks/machinery in the CLI repository
ConsoleJavaScript and TypeScriptsrc/specular/machinery/client-js in the console repository
Desktop appGopkg/clients/machinery-sdk in the desktop repository

We do not publish a Machinery client on its own, so calling the API from your own code means signing each request yourself with the headers above. The IAM service does publish its clients: @deployport/iam-sdk on npm and go.deployport.com/iam-sdk for Go, and both are generated the same way.

A refusal arrives as a problem with its own type, and the service’s message is the sentence to render. Machine and ssh failures and Assistant failures list the ones each subsystem returns.