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.get is client.ec2.instances.get(…) in TypeScript and Python and client.EC2.Instances.Get(…) in Go. Each method's documentation names the IAM action it needs.
  • Data: a method returns the data of 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 waitUntilAvailable on 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.0

A 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:

  1. credentials passed to the client;
  2. DCLOUD_ACCESS_KEY (<key id>:secret);
  3. DCLOUD_SESSION_TOKEN: an access token of your dcloud login session (dcloud auth token), sent as Authorization: Bearer; it lasts at most an hour;
  4. DCLOUD_WEB_IDENTITY_TOKEN_FILE and DCLOUD_ROLE_RN: an OIDC token exchanged for a key that lasts up to an hour and is renewed before it expires;
  5. the profile in ~/.dcloud/credentials.json written by dcloud 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. The dcloud CLI must be on PATH (or set DCLOUD_CLI). A sensitive call may answer STEP_UP_REQUIRED: run dcloud auth verify and 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.mjs

Reference

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 its DCLOUD_* twin is not set;
  • ~/.ews/credentials.json is read when ~/.dcloud/credentials.json does not exist (the SDKs never move it; the CLI does, and leaves ~/.ews as a link);
  • TypeScript: EwsClient, EwsApiError and the other Ews* classes are deprecated aliases of DcloudClient, DcloudApiError, …; Python: EwsError is DcloudError;
  • the console still serves releases built under the old names, and pip still finds them at …/pypi/simple/ews-sdk/;
  • access key ids starting EWS1 and DCLOUD are both accepted. The SDKs still send Authorization: EWS-ACCESS-KEY … and X-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
Did this page help you?