Connecting a tenant

Read-only tokens only

TFsmith asks for a READ-ONLY admin API token and never needs more. It physically cannot write to your tenant - there is no code path that does. The token is validated against your provider before anything is stored, then encrypted at rest (AES-256-GCM with a per-tenant data key, wrapped by the install's master key).

Okta

Base URL: https://yourorg.okta.com (your org URL, no trailing slash).

Token: Admin Console > Security > API > Tokens > Create token. Create it as a Read-Only Administrator: tokens inherit the permissions of the admin who creates them, so create (or sign in as) a user with the built-in Read-Only Administrator role and mint the token from that account.

Auth0

Base URL: https://your-tenant.us.auth0.com (your tenant domain).

Credentials: create a Machine-to-Machine application authorized for the Auth0 Management API with read:* scopes only (read:clients, read:connections, read:resource_servers, read:roles, read:rules, read:actions, and so on). The Connect form asks for that application's Client ID and Client Secret - TFsmith mints its own short-lived Management API tokens from them and only ever calls read endpoints.

Authentik

Base URL: https://authentik.example.com (your instance URL).

Token: Admin interface > Directory > Tokens & App passwords > create an API token for a user whose role is limited to viewing. Authentik permissions follow the user the token belongs to, so a read-only service account is the clean setup.

Connecting

+ Add tenant (administrators only) > name it, pick the provider, paste the base URL and token > Connect. TFsmith validates the token against the provider first - a bad URL or rejected token fails fast with the reason and nothing is stored.

On success TFsmith immediately pulls the tenant ONCE - this is the only automatic pull it will ever do (see The refresh model). Validating plus the first pull can take a minute on a large tenant; the Connect button shows progress while it works.

Editing a tenant

Settings > Tenants > Edit... (administrators only) - rename the tenant, correct its base URL, or rotate its API token. Leave the credential fields blank to keep the current one; the stored token is never displayed. If you change the URL or the token, TFsmith revalidates against the provider before saving, so a typo cannot leave you with a tenant that no longer authenticates. Rotating a token in your provider and pasting the new one here is the normal way to keep a tenant working; nothing you have already pulled is lost.

The provider cannot be changed - connect a new tenant for a different one. The tenant's internal slug also stays fixed, which is why a rename keeps everything already pulled.

Removing a tenant

Settings > Tenants > Remove (typed-name confirm). This deletes the tenant record and its stored export from TFsmith. Nothing is touched on the provider side - the token is read-only, and revoking it in your provider afterwards is good hygiene.

When a resource type says "not available"

TFsmith reads each resource type separately. If your tenant refuses one of them - because the feature is not licensed, or because the admin who created the API token does not have permission for it - that type is listed as not available with the reason from your provider, and everything else is still pulled normally. Hover the type to see the reason.

A common example is Okta: orgs without API Access Management return an error for authorization servers, so that one type shows as not available while apps, groups, policies and the rest export as usual. Types that are not available are left out of bundle exports.

This is deliberately different from a type your tenant simply has none of, which is hidden. If you see "not available", TFsmith was never allowed to look.