Bootstrap and authenticate

The tapstate control plane requires authentication for connector, artifact, connection, pipeline, and observation operations. A new server has one bootstrap window for creating its first administrator.

The Quickstart performs these steps automatically. Use this page after a tapstate server is already running, for example in that playground or in an environment managed separately from these docs.

Before you begin

• Start a preview server with its control port bound to loopback or another protected interface.
• Confirm GET /healthz returns ok.
• Install curl and jq for the HTTP examples.
• Choose a strong first-administrator password and keep it out of shell history.

The preview bootstrap endpoint accepts only a loopback caller. Do not expose an unbootstrapped server port to another host.

Set the server base URL once in the shell before using the HTTP examples. Use the address exposed by your running environment:

export TAPSTATE_URL=http://127.0.0.1:8080
curl --fail --silent --show-error --noproxy '*' "$TAPSTATE_URL/healthz"

Create the first administrator

Set credentials in the current shell, then call the loopback endpoint:

export TAPSTATE_URL=http://127.0.0.1:8080
export TAPSTATE_ADMIN_USER=admin
read -s TAPSTATE_ADMIN_PASSWORD
export TAPSTATE_ADMIN_PASSWORD

curl --fail-with-body --silent --show-error \
  -X POST "$TAPSTATE_URL/auth/bootstrap" \
  -H 'Content-Type: application/json' \
  --data "$(jq -n \
    --arg username "$TAPSTATE_ADMIN_USER" \
    --arg password "$TAPSTATE_ADMIN_PASSWORD" \
    '{username: $username, password: $password}')"

A successful first bootstrap returns HTTP 204 with no body. Once any user exists, another bootstrap request returns HTTP 409 with code control.bootstrap-closed.

The playground treats both results as an established administrator: 204 means it created the user; 409 means the bootstrap window was already closed.

Sign in with the CLI

Start an interactive session:

tapstate -w work

Then connect and sign in:

connect http://127.0.0.1:8080
login admin

The CLI asks for the password with masked input. A successful login keeps the session token in memory for that CLI process. Use logout or exit when finished.

The REPL does not expand $TAPSTATE_URL. Type the actual server URL in its connect command, including the port exposed by your running environment.

In the current preview, connected verbs can run inside this interactive session or as one-shot commands seeded with -c and -u. Prefer the session for a sequence that shares one login.

Sign in over HTTP

TOKEN="$(
  curl --fail-with-body --silent --show-error \
    -X POST "$TAPSTATE_URL/auth/login" \
    -H 'Content-Type: application/json' \
    --data "$(jq -n \
      --arg username "$TAPSTATE_ADMIN_USER" \
      --arg password "$TAPSTATE_ADMIN_PASSWORD" \
      '{username: $username, password: $password}')" \
  | jq -r '.token'
)"

Present the token on /api/** requests:

curl --fail-with-body --silent --show-error \
  "$TAPSTATE_URL/api/connectors" \
  -H "Authorization: Bearer $TOKEN"

The current session token lifetime is 15 minutes. When the signing secret is not configured, the single-node server creates a new secret at startup, so existing session tokens stop working after a restart.

Authentication results

API errors use the structured error envelope. Do not distinguish “unknown user” from “wrong password” in automation; both intentionally return the same authentication failure.

Security boundaries

• Keep the preview server on a trusted network path.
• Do not pass passwords as CLI arguments or commit .env files.
• Unset the shell variables when finished: unset TAPSTATE_ADMIN_PASSWORD TOKEN.
• Treat server restart as a new session boundary.
• The preview does not provide a complete production identity lifecycle or high-availability token-signing contract.

Next steps

• Register and test connectors
• Apply and run a pipeline
• REST API preview