Skip to main content
Service accounts let datumctl authenticate without a human at the keyboard. Instead of opening a browser, you point the CLI at a credentials file, and it signs in as the service account’s machine identity. Use this for continuous integration jobs, scheduled automation, and any headless runner where an interactive login is not possible.
Service accounts are created in the Datum Cloud portal, which is where you generate and download the credentials file. This page covers using those credentials with datumctl. To create a service account and download its key, see the portal guide on service accounts.

​
When to use a service account

Choose the authentication method that matches who — or what — is running the command:

Interactive login

A person at a terminal. Run datumctl login to authenticate through your browser (or datumctl login --no-browser for a device-code flow). Credentials refresh automatically and are tied to your user identity.

Service account

A pipeline, cron job, or agent with no human present. Run datumctl login --credentials <file> to sign in as a machine identity using a downloaded credentials file.
Service accounts are the right choice when:
  • The command runs unattended, so no one can complete a browser or device prompt.
  • You want a dedicated, auditable identity for automation rather than a personal account.
  • You need the same credentials to work reproducibly across many runners.

​
Log in with a credentials file

Once you have downloaded a credentials JSON file from the portal, authenticate by passing its path to datumctl login: 
datumctl login --credentials ./my-service-account.json
datumctl reads the file, requests an access token for the service account, and stores the resulting session so subsequent commands are authenticated. After login you can run any command as the service account: 
datumctl get organizations
Service-account login is non-interactive: it does not open a browser and does not prompt you to pick a context. Set the organization or project your commands should target explicitly — see Contexts & scoping — or pass --organization / --project on each command.

​
Targeting a custom environment

The credentials file is issued for a specific Datum Cloud environment. For a self-hosted or otherwise custom environment, also pass that environment’s auth hostname so token discovery points at the right server: 
datumctl login --credentials ./my-service-account.json --hostname auth.example.com
The default --hostname is auth.datum.net (production). You normally do not need --api-hostname — datumctl derives the API server from the auth hostname — but you can override it if your environment requires a specific API endpoint.

​
Confirming the active identity

To verify which identity is active, use: 
datumctl whoami
The service account also appears in the local account list, where its client_email is shown as the name: 
datumctl auth list

​
The credentials file

The credentials file is a JSON document you download from the portal. It looks like this: 
{
  "type": "datum_service_account",
  "client_email": "ci-deployer@example",
  "client_id": "1234567890",
  "private_key_id": "abc123",
  "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----\n",
  "token_uri": "https://auth.datum.net/oauth/v2/token",
  "api_endpoint": "https://api.datum.net",
  "scope": "openid profile email offline_access"
}
Key fields:
FieldPurpose
typeMust be datum_service_account. datumctl rejects any other value.
client_idThe service account’s identity. Required.
private_key_idIdentifies which signing key is in use. Required.
private_keyPEM-encoded private key used to sign the login request. Required.
client_emailHuman-readable identity, shown as the account name in datumctl auth list.
token_uri, api_endpoint, scopeEnvironment and authorization details carried in the file.
The credentials file contains a private key. Treat it like a password: never commit it to source control, restrict its file permissions, and store it in your CI system’s secret manager. Anyone with the file can authenticate as the service account.
If login fails, datumctl reports exactly what is wrong — a missing required field, an unreadable file, or a type that is not datum_service_account — so you can correct the file and retry. To inspect the token request in detail while troubleshooting, add --debug, which prints the login JWT’s claims to standard error.

​
Credential storage on headless runners

After a successful login, datumctl stores the session in your operating system’s keyring. On many headless CI runners no system keyring is available, so datumctl automatically falls back to an on-disk file at ~/.datumctl/credentials.json. This fallback is expected on CI, but note:
  • The file is written with owner-only (0600) permissions, but is not encrypted. Treat the runner’s home directory as sensitive and use ephemeral runners where possible.
  • When the fallback engages, datumctl prints a one-time warning noting that it is using file-based credential storage. This is informational — your commands still work.
Because the fallback file is unencrypted, prefer runners whose home directory is discarded after the job completes, and rely on your CI secret manager as the source of truth for the credentials file rather than persisting the stored session.
Last modified on July 2, 2026