Authentication with tcloud CLI

This guide covers how to authenticate with the Thalassa Cloud Platform using the tcloud CLI.

Authentication Methods

The tcloud CLI supports these authentication methods:

1. Browser OIDC login (default for interactive use)
2. Personal Access Token (PAT) (automation and non-interactive use)
3. OIDC client credentials (service accounts and automation)
4. Access tokens

For day-to-day work on a trusted workstation, prefer browser OIDC. Use personal access tokens or client credentials when you need non-interactive authentication (CI/CD, scripts, headless environments).

Browser OIDC login (recommended)

Browser-based OIDC is the default when you run tcloud context create or tcloud context login without other credentials. The CLI opens your browser, completes the OIDC authorization code flow with PKCE, and stores credentials securely.

Create a context

tcloud context create --name production

tcloud opens your default browser for sign-in and binds the session to the context. Optionally set organisation scope during create:

tcloud context create --name production --organisation=my-company

Re-authenticate an existing context

tcloud context login

To switch an existing PAT-based context to browser OIDC:

tcloud context login --browser

Credential storage

Access and refresh tokens are stored in your OS keychain (macOS Keychain, Windows Credential Manager, or Linux secret service). The config file (~/.tcloud on Linux/macOS) holds context metadata such as API endpoint, organisation, and project scope — not the tokens themselves.

If you migrated from an older setup with credentials in the config file:

tcloud context fix --migrate-credentials

Personal Access Token (PAT)

Personal Access Tokens remain supported for automation and integrations. Prefer them when a browser session is not available.

Creating a Personal Access Token

1. Log in to your Thalassa Cloud Console
2. In the top right, navigate to /personal-access-tokens
3. Click “Create Personal Access Token”
4. Give your token a descriptive name
5. Select the appropriate permissions
6. Optionally, configure the expiry date (recommended)
7. Copy the generated token (you won’t be able to see it again)

Using a Personal Access Token

Method 1: Create a Context (Recommended)

tcloud context create --name my-context \
  --api=https://api.thalassa.cloud \
  --token=your-personal-access-token

Method 2: Use Global Flags

tcloud --api=https://api.thalassa.cloud \
  --token=your-personal-access-token \
  me

Optionally, you can also use --organisation to target a specific organisation. By default, it will select the first organisation you are a member of. You can always switch between organisations by using tcloud context organisation <organisation>.

Security Best Practices

• Never commit tokens to version control
• Rotate tokens regularly
• Use the minimum required permissions
• Prefer browser OIDC for interactive use so long-lived tokens are not needed on workstations

OIDC client credentials

For service accounts and non-interactive OIDC flows:

tcloud context create --name automation \
  --api=https://api.thalassa.cloud \
  --client-id=<oidc-client-id> \
  --client-secret=<oidc-client-secret> \
  --organisation=<org-slug>

Context Management

Contexts allow you to manage multiple authentication configurations and switch between them easily. See Context Management for details.

Creating Contexts

# Interactive browser login (default)
tcloud context create --name production --organisation=my-org

# Non-interactive with a PAT
tcloud context create --name staging \
  --api=https://api.thalassa.cloud \
  --token=staging-token \
  --organisation=my-org-staging

Listing Contexts

tcloud context list

Switching Contexts

# Use a specific context
tcloud --context=production me

# Set default context
tcloud context use production

Deleting Contexts

This deletes the current context.

tcloud context delete

Verifying Authentication

After setting up authentication, verify it’s working:

tcloud me organisations

You should see output similar to:

ID                      NAME            SLUG
d0nm4fiacp3nbhm3nv2g    my company      my-company-betyt