Auth provider

An auth provider is a reusable description of how to obtain a credential, so that no request ever carries a pasted token. You define it once; Tinspec fetches the token, caches it until it expires, and injects it into every request and chain that references the provider.

Three kinds

script

You supply JavaScript. It runs in the engine’s sandboxed QuickJS runtime with a controlled fetch, and returns a token. This is the escape hatch for any login flow that is not a first-class integration — a bespoke /auth/login endpoint, a signed assertion exchange, a two-step handshake.

async function authenticate({ env, config, secret, fetch, sender }) {
  const res = await fetch(`${env.baseUrl}/auth/login`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      username: sender.id,
      password: secret(sender.secretRef),
    }),
  });
  const json = await res.json();
  return { token: json.access_token, expiresIn: json.expires_in };
}

The exact contract — what each argument gives you — is in Auth script contract.

integration

First-class support for an identity provider, configured rather than scripted. At v0.1.0-preview.9 the integrations are:

keycloak, clerk, auth0, firebase, supabase.

keycloak and auth0 take a grant (password or client_credentials) in their config; firebase and supabase exchange email and password for a token.

request

The token comes from an ordinary Tinspec request — any protocol, so you can fetch a token over gRPC and use it on HTTP calls — plus one extraction saying where in the response the token is. The result is exposed as {{token}}.

Injection

Where the credential goes is part of the provider, not repeated on every request:

inject:
  target: header      # header | query | cookie
  name: Authorization
  template: "Bearer {{token}}"

Omit the block and the default applies: Authorization: Bearer {{token}}.

Secrets are references, never values

A provider’s YAML holds names, not credentials:

• config is non-secret only — base URL, realm, client id, token URL, scope, domain.
• secretRefs lists OS-keychain key names.
• A sender’s secretRef names that identity’s own keychain entry.

The values live in your OS keychain or a machine-local encrypted store, chosen in Settings → Security. This is why an auth provider file is safe to commit, and why cloud sync can move provider definitions between machines without ever moving a credential.

Caching

A fetched token is cached until it expires and shared across every send that uses the provider — including chain steps and requests driven by an agent. You are not re-authenticating on every call.

If you need the raw token for something outside Tinspec, Copy token hands it to the clipboard from that same cache. The provider’s Test action stays masked.

Senders

One provider, many identities — see Sender.