Automation credentials

A pipeline or backend uses an automation client (also called an M2M client) owned by your organization. An owner or admin creates it; the application uses its client ID and secret. This works the same way on hosted Tanomis and a self-hosted deployment.

At a glance

• An owner or admin creates the client in the Console or with tanomis m2m create; the secret is shown once.
• A job or service sets TANOMIS_API_URL, TANOMIS_CLIENT_ID, and TANOMIS_CLIENT_SECRET; tanomis then runs unattended, and a backend does the same OAuth exchange itself.
• Profiles: observe, invoke, deploy. A client reaches every tenant in its organization, including future ones.
• Rotation is additive; disable stops access at once, even for an unexpired token.

Create a client in the Console

1. Open Settings → Organization → Machine clients.
2. Choose Create client, give it a name, and select a permission profile.
3. Save the platform origin, client ID, and client secret in your CI or service secret manager before closing the dialog. The secret is shown once.

For hosted Tanomis the platform origin is https://api.tanomis.com. For a self-hosted installation, use your deployment’s public API origin. This is an HTTP address, not an OAuth audience identifier.

You can also create a client while signed in as an organization owner or admin:

Terminal

tanomis m2m create production-automation --profile deploy

Use --org ORGANIZATION if you belong to more than one organization. The output includes Client: (the platform record ID used for management), Client ID: (the OAuth credential ID), Client secret:, and the credential ID and expiry. Store the secret securely; do not send this output to a shared job log.

Give tanomis three values

Inject these variables from your secret manager. The values below are placeholders:

Terminal

export TANOMIS_API_URL=https://api.tanomis.com
export TANOMIS_CLIENT_ID='<client-id>'
export TANOMIS_CLIENT_SECRET='<client-secret>'

tanomis agent ls --tenant northwind-sandbox

No tanomis login step is needed. tanomis discovers authentication settings from the platform, exchanges the credentials for an OAuth access token, and keeps the token in memory. It does not save the machine secret in the human login credential store. For a private certificate authority, configure TANOMIS_CA_BUNDLE with your CA bundle path.

Choose a tenant explicitly for predictable automation. Without one, tanomis can select the organization’s sole ready tenant or its ready default. A selected tenant controls where a command runs; it does not narrow what the credential can reach.

Choose permissions

Profile	What it allows
observe	Read agents, builds, sessions, operations, tenants, workspaces, and identity. No session file content.
invoke	observe, plus run agents, manage session files, and run tanomis eval ci.
deploy	observe, plus register, build, deploy, promote, and cancel agent builds.

deploy does not include invoke or access to the evaluation API. invoke reaches only the evaluation routes tanomis eval ci uses: it reads an agent’s checks and datasets, replays a dataset through a version, and compares the results. It cannot change checks, guards, or datasets. Automated registration and deployment are tenant-scoped; this credential cannot publish deployment-wide agents. Organization membership, tenant creation and offboarding, and machine credential management require a signed-in human owner or admin.

Every client reaches every active tenant with a ready attachment to its organization, including future tenants. There are no per-tenant grants for machine clients. Use separate organizations when credentials must be isolated between groups of tenants.

The profiles supply a standard set of scopes. Owners and admins can also select supported scopes with tanomis m2m permissions CLIENT --scopes read:agents,read:identity. Removing a scope or disabling the client takes effect at the next authorization decision, even for an existing token. Adding scopes also requires a newly issued token containing them.

Rotate and revoke

Run lifecycle commands as a human owner or admin. If your shell has machine credentials set, unset TANOMIS_CLIENT_ID and TANOMIS_CLIENT_SECRET before using your human login. Use the platform record ID from Client: or tanomis m2m ls, not the display name or OAuth client ID.

Terminal

tanomis m2m ls
tanomis m2m get "$CLIENT"
tanomis m2m rotate "$CLIENT" --label rotation --expires-in-days 90

Rotation adds a credential without invalidating the old one. Update your jobs with the new secret, verify they work, then revoke the old credential ID shown by tanomis m2m get:

Terminal

tanomis m2m revoke "$CLIENT" "$OLD_CREDENTIAL"

Revocation stops new tokens once credential cleanup completes. Tokens already issued can remain valid until expiry; disable the client if you need to stop access immediately.

An organization can have 20 non-deleted clients. Each client can have two live, unexpired credentials. The default credential lifetime is 90 days; the maximum is 365 days. If both slots are occupied, revoke an unused credential before rotating again.

A lost create or rotate response cannot be replayed to recover the secret. Inspect the client, revoke the unusable credential, and rotate again. --request-id allows safe retries of the same operation, but a replay never returns the secret a second time.

Change or stop access

Terminal

tanomis m2m rename "$CLIENT" production-deployer
tanomis m2m permissions "$CLIENT" --profile observe
tanomis m2m disable "$CLIENT"
tanomis m2m enable "$CLIENT"
tanomis m2m delete "$CLIENT"

Disable is reversible. Delete withdraws access and starts credential cleanup. Neither requires waiting for existing access tokens to expire. Lifecycle operations are attributed to the human who performed them, without recording the secret.

Existing COG_LOGTO_* CLI configuration remains supported for compatibility. New organization clients should use the three provider-neutral variables above.

Where to go next

• Deploy from CI
• Authenticate a backend
• Organization management API
• M2M CLI reference