SDKs
Call the API from TypeScript, Python or Go, with retries, paging and waiters.
The Deutsche Cloud SDKs call the Deutsche Cloud API from TypeScript, Python and Go. Each has one method for every API
operation, named after it (client.ec2.instances.list()), and handles signing in, retries, paged
lists and waiting for a resource to be ready. They sign in with an access key and can do exactly
what that key's IAM user is allowed to do.
| Language | Package | Needs |
|---|---|---|
| TypeScript | @dcloud/sdk |
Node.js 20.3+ |
| Python | dcloud-sdk (import dcloud) |
Python 3.9+ |
| Go | github.com/deutschlandgpt/ews/sdk/go (package dcloud) |
Go 1.23+ |
Concepts
- Operation: every API call, as
service.resource.operation. The SDK method has the same name in the language's own casing:ec2.instances.getisclient.ec2.instances.get(…)in TypeScript and Python andclient.EC2.Instances.Get(…)in Go. Each method's documentation names the IAM action it needs. - Data: a method returns the
dataof the API's{"success": true, "data": …}answer. - Access key:
<key id>:secret, created under IAM → Access keys, or exchanged for an OIDC token in CI. - Waiter: a method that polls a resource until it reaches a state, such as
waitUntilAvailableon a network.
Install
Every console serves the SDKs built against its own API, with no account needed.
https://<your console>/api/sdk lists the versions, the files with their SHA-256 sums, and the
install commands for the newest version. Replace console.example.com and the version below:
# TypeScript: the npm tarball, by URL
npm install https://console.example.com/api/sdk/files/0.1.0/dcloud-sdk-0.1.0.tgz
# Python: the console is a package index for dcloud-sdk
pip install --index-url https://console.example.com/api/sdk/pypi/simple/ dcloud-sdk
# Go: the console is a module proxy for github.com/deutschlandgpt/ews/sdk/go
GOPROXY=https://console.example.com/api/sdk/go,https://proxy.golang.org,direct \
GONOSUMDB=github.com/deutschlandgpt/ews/sdk/go \
go get github.com/deutschlandgpt/ews/sdk/go@v0.1.0A version's packages never change, and the console keeps every version it has served, so lock
files, pip hashes and go.sum keep working after the console is upgraded. GONOSUMDB is needed
because the module is not in Go's public checksum database.
Sign in
Every SDK looks for credentials in the same order as the dcloud CLI, and stops at the first it
finds:
- credentials passed to the client;
DCLOUD_ACCESS_KEY(<key id>:secret);DCLOUD_SESSION_TOKEN: an access token of yourdcloud loginsession (dcloud auth token), sent asAuthorization: Bearer; it lasts at most an hour;DCLOUD_WEB_IDENTITY_TOKEN_FILEandDCLOUD_ROLE_RN: an OIDC token exchanged for a key that lasts up to an hour and is renewed before it expires;- the profile in
~/.dcloud/credentials.jsonwritten bydcloud login(DCLOUD_PROFILE, else the current one). For a Touch ID or browser sign-in (CLI sign-in) the SDK asks the CLI for a fresh token (dcloud auth token --json) whenever the last one is about to expire, so a script on your laptop runs as you with no key at all. ThedcloudCLI must be onPATH(or setDCLOUD_CLI). A sensitive call may answerSTEP_UP_REQUIRED: rundcloud auth verifyand try again within five minutes.
In code: cliSessionCredentials({ profile }) (TypeScript), CliSessionCredentials(profile=…)
(Python), &dcloud.CLISessionProvider{Profile: …} (Go).
The console address is the one passed to the client, else DCLOUD_API_URL, else the profile's.
Create, list and delete
import { DcloudClient } from '@dcloud/sdk';
const client = new DcloudClient();
const { id } = (await client.ec2.vpcs.create({ regionId: 'de1', name: 'main' })) as { id: string };
await client.ec2.vpcs.waitUntilAvailable({ id });
console.log(await client.ec2.vpcs.list());
await client.ec2.vpcs.delete({ id });from dcloud import Client
client = Client()
vpc = client.ec2.vpcs.create(region_id="de1", name="main")
client.ec2.vpcs.wait_until_available(id=vpc["id"])
client.ec2.vpcs.delete(id=vpc["id"])import dcloud "github.com/deutschlandgpt/ews/sdk/go"
client, err := dcloud.New(dcloud.Options{})
vpc, err := client.EC2.VPCs.Create(ctx, &dcloud.EC2VPCsCreateInput{RegionID: "de1", Name: dcloud.String("main")})Use it in GitHub Actions without a stored key
Register GitHub as an identity provider and create a role that trusts your repository (see IAM). Then write the job's OIDC token to a file and set three variables; the SDK does the exchange:
permissions:
id-token: write
contents: read
jobs:
deploy:
runs-on: ubuntu-latest
env:
DCLOUD_API_URL: https://console.example.com
DCLOUD_ROLE_RN: rn:ews::<org id>:iam:role/<role id>
DCLOUD_WEB_IDENTITY_TOKEN_FILE: /tmp/oidc-token
steps:
- uses: actions/checkout@v4
- name: Fetch the job's OIDC token
run: |
curl -sSf -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
"$ACTIONS_ID_TOKEN_REQUEST_URL&audience=$DCLOUD_API_URL" | jq -r .value > "$DCLOUD_WEB_IDENTITY_TOKEN_FILE"
- run: node deploy.mjsReference
| Behaviour | What the SDKs do |
|---|---|
| Retries | 429, 502, 503, 504 and connection errors, with jittered exponential backoff and Retry-After; up to 4 attempts by default |
| Unsafe calls | POST and PATCH are retried only on 429 and on connection errors from before the request was sent |
| Errors | an API error carries the HTTP status, the API's message and, for a 400, each invalid field |
| Paged lists | lists the API returns a page at a time (audit log, images, commits, job logs, sent mail, table rows) have an …All iterator |
| Waiters | instances, volumes, networks, NAT gateways, databases, caches, deployments, apps, Kubernetes clusters, load balancers |
| Region | X-EWS-Region from the client, DCLOUD_REGION or the profile |
| User-Agent | dcloud-sdk-typescript/<version>, dcloud-sdk-python/<version>, dcloud-sdk-go/<version> |
Formerly ews
Until 18 November 2026 the SDKs were named after the old short name ews: @ews-cloud/sdk,
ews-sdk (import ews_sdk) and Go package ews. None of those was published to a registry, so
installing from your console as above gives you the new names. What you wrote for the old ones
keeps working until at least 31 December 2027:
- every
EWS_*variable (EWS_ACCESS_KEY,EWS_API_URL,EWS_PROFILE,EWS_REGION, …) is read when itsDCLOUD_*twin is not set; ~/.ews/credentials.jsonis read when~/.dcloud/credentials.jsondoes not exist (the SDKs never move it; the CLI does, and leaves~/.ewsas a link);- TypeScript:
EwsClient,EwsApiErrorand the otherEws*classes are deprecated aliases ofDcloudClient,DcloudApiError, …; Python:EwsErrorisDcloudError; - the console still serves releases built under the old names, and pip still finds them at
…/pypi/simple/ews-sdk/; - access key ids starting
EWS1andDCLOUDare both accepted. The SDKs still sendAuthorization: EWS-ACCESS-KEY …andX-EWS-Region, which every console reads.
What is not supported
- The public registries (npm, PyPI, a public Go repository): install from your console.
- Typed responses: methods return plain JSON until the API documents its response shapes.
- Async Python: the Python client is synchronous.
- Java and C#.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
No endpoint |
no endpoint passed, no DCLOUD_API_URL, no profile |
set DCLOUD_API_URL to your console's address |
No credentials |
none of the four sources is set | set DCLOUD_ACCESS_KEY, or run dcloud auth login |
HTTP 403: Forbidden |
the key's IAM user lacks the action | attach a policy granting the action the method names |
InvalidIdentityToken: token audience is not accepted |
the job asked for another audience | request your console's address as the audience |