tcurl — T Cloud Public API Client¶

A CLI tool and Python module for making REST API calls to T Cloud Public endpoints.

Supports bearer token, AK/SK (SDK-HMAC-SHA256), and metadata server authentication.

It is more of a tool to use for creating integration scripts rather than outright application.

Requirements¶

Python 3.10+
requests library
Optional: icecream (debug logging, falls back gracefully)
Optional: pyyaml (YAML output format)

Installation¶

# Core dependencies
pip install requests

# Optional:
pip install icecream pyyaml

# For interactive login (urwid-based TUI form):
pip install urwid

Or install via pip from source:

pip install .

This installs two console scripts:

Command	Description
`tcurl`	Main CLI tool for API calls, credentials, etc.
`tcurl-login`	Interactive TUI login (username/password/OTP form)

Usage¶

# As a standalone script
python tcurl.py [global-opts] <command> [command-opts]

# Or using the installed console scripts:
tcurl [global-opts] <command> [command-opts]
tcurl-login [options]

Global options¶

Option	Description
`-v`, `--verbose`	Show additional information
`-V`, `--version`	Show version and exit

Commands¶

Authentication¶

Command	Description
`login`	Issue a bearer token (password or unscoped token exchange)
`logout`	Revoke a previously issued token

Credential retrieval¶

Command	Description
`metadata`	Retrieve temporary AK/SK from the metadata server
`aksk`	Issue temporary AK/SK credentials from a bearer token

REST API calls¶

Command	Description
`get`	Make a GET request
`post`	Make a POST request (requires body)
`put`	Make a PUT request (requires body)
`patch`	Make a PATCH request (requires body)
`delete`	Make a DELETE request
`head`	Make a HEAD request
`options`	Make an OPTIONS request

Output formats¶

Every command except logout supports the --format / -f option:

Format	Description
`raw`	Space-joined values (default)
`json`	Pretty-printed JSON
`yaml`	YAML output (requires `pyyaml`)
`shell`	Shell `export` statements for sourcing

Authentication¶

Credentials are resolved in this order:

Command-line arguments
Metadata server (http://169.254.169.254/openstack/latest/securitykey)
Environment variables

Bearer token¶

# Environment
export OS_AUTH_TOKEN=...
python tcurl.py get https://...

# Command line
python tcurl.py get --token=eyJ... https://...

AK/SK (SDK-HMAC-SHA256)¶

# Environment
export OS_ACCESS_KEY=...
export OS_SECRET_KEY=...
export OS_SECURITY_TOKEN=...   # optional, for temp credentials

# Command line
python tcurl.py get --ak=... --sk=... https://...

When doing AK/SK calls, you can scope the request with any of these mutually exclusive options:

Option	Description
`--project-id`	Scope to a specific project ID
`--project-name`	Scope to a project by name
`--domain-id`	Scope to a specific domain ID

Metadata server¶

# Fetch credentials first
eval $(python tcurl.py metadata --format shell)

# Then use them
python tcurl.py get https://...

Alternatively, pass --metadata directly to any REST verb:

python tcurl.py get --metadata https://...

You can also use a custom metadata URL with --url:

# In two steps
python tcurl.py metadata --url=http://custom.metadata/securitykey --format shell

# Or inline with any REST verb
python tcurl.py get --url=http://custom.metadata/securitykey https://...

REST API call options¶

All REST verb commands (get, post, put, patch, delete, head, options) accept these authentication options (mutually exclusive):

Option	Description
`--token` / `-t`	Bearer token (or env `OS_AUTH_TOKEN` / `OS_TOKEN`)
`--ak` / `-a`	Access Key (or env `OS_ACCESS_KEY`)
`--sk` / `-s`	Secret Key (or env `OS_SECRET_KEY`)
`--securitytoken` / `-T`	Security token for temp credentials (or env `OS_SECURITY_TOKEN`)
`--metadata` / `-m`	Fetch credentials from the standard metadata endpoint
`--url` / `-U`	Fetch credentials from a custom metadata URL

And these general options:

Option	Description
`--header` / `-H`	Additional header in `Key:Value` format (repeatable)
`--format` / `-f`	Output format: `raw`, `json`, `yaml`, `shell`

Login (issue a bearer token)¶

# Using username + password
python tcurl.py login --username=user@example.com --password=... --domain=OTC0000xxxx

# Interactive (prompts for missing credentials via stdin)
python tcurl.py login --interactive

# Interactive with urwid-based TUI form (requires urwid)
tcurl-login

# Interactive with Virtual MFA OTP
python tcurl.py login --interactive --totp=123456

# Exchange an unscoped token for a scoped one
python tcurl.py login --token=eyJ... --project=eu-de_project

# Scope to a region
python tcurl.py login --username=... --password=... --domain=... --region=eu-de

# Custom auth URL
python tcurl.py login --username=... --password=... --domain=... --auth-url=https://iam.eu-de.otc.t-systems.com

Options:

Option	Description
`--username` / `-u`	Username for password-based authentication
`--password` / `-P`	Password (or env `OS_PASSWORD`)
`--domain` / `-D`	User domain name, e.g. `OTC0000xxxx` (or env `OS_USER_DOMAIN_NAME`)
`--token` / `-t`	Unscoped token to exchange for a scoped one
`--project` / `-p`	Scope to a project name (derives region from prefix)
`--region` / `-R`	Scope to a region (or env `OS_TENANT_NAME`)
`--auth-url` / `-A`	Custom auth URL (or env `OS_AUTH_URL`)
`--interactive` / `-i`	Prompt for credentials interactively
`--totp`	Virtual MFA one-time passcode

The login command outputs the token and expiry in the selected format (--format json is recommended for inspection).

Logout (revoke a token)¶

# Revoke a specific token
python tcurl.py logout eyJ...

# Revoke the token from the environment and export shell commands
python tcurl.py logout --shell

The --shell flag (or --format shell) outputs export statements suitable for eval, clearing the OS_AUTH_TOKEN variable after revocation.

Temporary AK/SK¶

# Issue temporary credentials valid for 15 minutes (default)
python tcurl.py aksk --token=eyJ...

# Custom duration (up to 24 hours = 86400 seconds)
python tcurl.py aksk --maxage=3600 --token=eyJ...

# Using environment variable for the token
export OS_AUTH_TOKEN=eyJ...
python tcurl.py aksk

# With a custom region or auth URL
python tcurl.py aksk --region=eu-de --maxage=7200

Options:

Option	Description
`--token` / `-t`	Bearer token (or env `OS_AUTH_TOKEN` / `OS_TOKEN`)
`--maxage` / `-M`	Max lifetime in seconds (default: 900 / 15 min)
`--region` / `-R`	Region for auth URL (or env `OS_TENANT_NAME`)
`--auth-url` / `-A`	Custom auth URL (or env `OS_AUTH_URL`)
`--format` / `-f`	Output format: `raw`, `json`, `yaml`, `shell`

The issued AK/SK will have the same permissions as the original bearer token.

Project layout¶

Path	Description
`tcurl.py`	CLI tool and importable module
`tcurl_login.py`	Interactive TUI login form (urwid-based)
`setup.py`	Package installer / distribution
`tests/`	Test scripts and examples
`docs/`	Sphinx documentation source
`_attic/`	Archived scripts (not part of the project)
`DEVNOTES.md`	Developer notes

Use as a Python module¶

tcurl.py and tcurl_login.py can be imported and used programmatically:

from tcurl import (
    creds, add_headers, add_project_id, add_domain_id,
    metadata_config, resolve_auth_url,
    login, logout, temp_aksk,
    OTCAkSkAuth, OBSAuth,
)

# Resolve the IAM endpoint for a region
auth_url = resolve_auth_url(region='eu-de')
# => 'https://iam.eu-de.otc.t-systems.com'

# Fetch credentials from metadata server
credential = metadata_config()
# => {'access': '...', 'secret': '...', 'securitytoken': '...', 'expires_at': '...'}

# Build request kwargs
kwargs = creds(token='eyJ...')
# => {'headers': {'X-Auth-Token': 'eyJ...'}}

# Or use AK/SK
kwargs = creds(ak='...', sk='...', securitytoken='...')
# => {'auth': OTCAkSkAuth(...)}

# Scope an AK/SK request to a project
add_project_id(kwargs, 'eu-de_12345')
add_domain_id(kwargs, 'OTC0000xxxx')

# Add custom headers
add_headers(kwargs, ['X-Request-Id:my-id'])

# Make the request
import requests
resp = requests.get('https://...', **kwargs)

# Issue a bearer token programmatically
token, details = login(
    username='user@example.com',
    password='...',
    domain='OTC0000xxxx',
    project='eu-de_project',
)
# token => 'eyJ...'
# details => full JSON response from IAM

# Issue temporary AK/SK from a token
creds = temp_aksk(token='eyJ...', max_secs=3600)
# => {'access': '...', 'secret': '...', 'securitytoken': '...', 'expires_at': '...'}

# Revoke a token
logout(token='eyJ...')

The tcurl_login module provides an interactive urwid-based form:

from tcurl_login import CredentialForm

form = CredentialForm()
result = form.run()
# => {'username': '...', 'password': '...', 'domain': '...', 'totp': '...'}

Notes¶

The --project short flag (-p) in the login command refers to a project name, not a project ID.
When using --project in login, the region is automatically derived from the project name (the part before the first _).
All REST verb commands accept get, post, put, patch, delete, head, and options both in lowercase (e.g. get) and uppercase (e.g. GET).
The tool supports reading arguments from a file using the @ prefix (e.g. python tcurl.py get @args.txt).
Credential resolution order for REST verbs: command-line arguments → metadata server → environment variables.
The --region and --project options on login are mutually exclusive. When --project is used, the region is derived from the project name prefix.
The --interactive mode reads from stdin when running in a TTY, or silently from stdin when piped (useful for automation scripts).
The tcurl-login console script (urwid-based TUI) requires urwid. It provides a dialog-style form with password masking and Tab navigation.

tcurl — T Cloud Public API Client¶

Requirements¶

Installation¶

Usage¶

Global options¶

Commands¶

Authentication¶

Credential retrieval¶

REST API calls¶

Output formats¶

Authentication¶

Bearer token¶

AK/SK (SDK-HMAC-SHA256)¶

Metadata server¶

REST API call options¶

Logout (revoke a token)¶

Temporary AK/SK¶

Project layout¶

Use as a Python module¶

Notes¶

tcurl

Navigation

Related Topics