Authenticate a backend

Create an automation client with the invoke profile for an application that runs agents, or observe for a read-only integration. Keep its secret on your backend. Never embed it in browser code or a mobile application.

Your service needs three configuration values: the platform API origin, client ID, and client secret. For hosted Tanomis, the origin is https://api.tanomis.com. If you use tanomis in your service, the three environment variables handle the following steps automatically.

At a glance

• Three values: the platform API origin, the client ID, and the client secret. Never in a browser or a mobile app.
• Discover the token endpoint from the platform; exchange the credentials with OAuth client credentials; send the token as a bearer with a tenant selector.
• Effective permissions are the intersection of the token’s scopes and the client’s current permissions; a denial is an access decision, not a reason to fetch more tokens.

Discover authentication settings

Request the public configuration from your trusted platform origin:

GET /v1/cli-config HTTP/1.1
Host: api.tanomis.com

The response’s m2m object supplies issuer, audience, and scopes. If it is missing, machine authentication is not available on that deployment. Fetch the issuer’s OpenID Connect discovery document at issuer + /.well-known/openid-configuration and read token_endpoint. For deployments whose issuer is a base origin, tanomis also supports discovery at issuer + /oidc/.well-known/openid-configuration if the first location is unavailable.

Do not substitute the audience for the platform origin. An audience is the identifier of the resource receiving the token and need not be a reachable address. Discover it rather than hardcoding a provider’s domain or a hosted deployment’s identifier.

Exchange the credentials

Use your backend’s HTTP or OAuth library to POST to the discovered token endpoint with HTTP Basic authentication using the client ID and secret. Send form-encoded fields:

Content-Type: application/x-www-form-urlencoded
Authorization: Basic <encoded-client-id-and-secret>

grant_type=client_credentials
resource=<discovered-audience>
scope=<space-separated-discovered-scopes>

The body above lists the fields separately for readability; your library must URL-encode them as one form. Requesting a scope does not grant it: effective permissions are the intersection of the token’s scopes and the client’s current permissions.

Use HTTPS for discovery and token requests, validate certificates, and do not forward credentials through redirects. Read the returned access_token, token_type, and expiry in memory. Reuse an unexpired token and obtain a new one before expiry; this flow does not use a human refresh token. Keep token responses and authorization headers out of application logs.

Call the platform

Send the token to the platform API origin and select the target tenant for tenant-scoped requests:

GET /v1/agents HTTP/1.1
Host: api.tanomis.com
Authorization: Bearer <access-token>
X-Tenant-ID: <organization-tenant-id>

The tenant must be active and ready in the client’s organization. Use the public platform API for agent, session, and run requests. Do not send organization machine tokens directly to an independent Registry endpoint.

Disabling or deleting the client, removing a scope, or offboarding the tenant can deny a request while the token is still unexpired. Treat a permission denial as an access decision, not a reason to endlessly fetch new tokens. Machines cannot call the human-only credential or tenant lifecycle APIs to restore their own access.

Where to go next

• Invoke from your application: the six requests that run an agent.
• Automation credentials: profiles, rotation, revocation.
• Platform API: every endpoint.