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.
Where it answers
Section titled “Where it answers”The API is regional, one host per region:
| Region | Base URL |
|---|---|
us-east-2 | https://machinery.us-east-2.api.deployport.io/api |
us-west-2 | https://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.
How a caller authenticates
Section titled “How a caller authenticates”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:
| Variable | What it carries |
|---|---|
DEPLOYPORT_ACCESS_KEY_ID | the access key id |
DEPLOYPORT_SECRET_ACCESS_KEY | the secret |
DEPLOYPORT_REGION | the 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.
Permissions
Section titled “Permissions”Every operation asserts an IAM action over a resource, and the action names the resource it is scoped over:
| Action | Scoped over |
|---|---|
machinery:GetMachine | machinery:Machine(<machine-id>) |
machinery:CreateMachine | machinery:Account(*), and machinery:WorkerPool(<worker-pool-id>) when the launch names a worker pool |
machinery:RunCommand | machinery: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.
Where the clients live
Section titled “Where the clients live”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:
| Client | Language | Where it lives |
|---|---|---|
| CLI | Go | the deployport binary, built from sdks/machinery in the CLI repository |
| Console | JavaScript and TypeScript | src/specular/machinery/client-js in the console repository |
| Desktop app | Go | pkg/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.
Errors
Section titled “Errors”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.