docs(auth): switch auth connection docs from tailorctl to SDK#154
Merged
Conversation
- Rewrite the AuthConnection guide to use defineAuth() connections and tailor-sdk CLI instead of tailorctl, reflecting the in-place update behavior from sdk#1603 - Sync docs/sdk/services/auth.md from the SDK repo to pick up the same change - Update the setup-auth-connections tutorial's change-detection note to describe in-place updates instead of the old hash-based revoke/recreate behavior
Switch runtime token examples from auth.getConnectionToken() (the defineAuth() return value, which requires importing tailor.config.ts into runtime code) to authconnection.getConnectionToken() from @tailor-platform/sdk/runtime.
- Sync docs/sdk/services/auth.md and docs/sdk/testing.md from the SDK repo - authconnection.getConnectionToken() from @tailor-platform/sdk/runtime is now type-checked against defineAuth()'s connections via a generated ConnectionNameRegistry (mirroring MachineUserNameRegistry); document the narrowing and the tailor-sdk generate/deploy step needed to refresh it - Fix Token Properties to list only access_token, matching the corrected AuthConnectionTokenResult shape (GetConnectionSessionToken never returns refresh_token, token_type, or expires_at) - Fix stray tailor-sdk apply references to deploy, the actual command name
…ivity - Add Option B: fully managing a connection (create, authorize, revoke, delete) from the Console via 'tailor-sdk authconnection open', with no tailor.config.ts changes - Add a Choosing a Management Method section explaining that a connection is owned by exactly one side at a time, based on the SDK's ownership-label mechanism (planAuthConnections/confirmUnmanagedResources in the SDK source): a Console-created connection has no label and deploy leaves it alone, but declaring the same name in defineAuth() prompts to adopt it into config management, after which config always wins - Add the 'authconnection delete' command (removes the connection entirely, vs 'revoke' which only invalidates tokens) and a note not to delete a config-managed connection out of band - Point the setup-auth-connections tutorial at the guide's Setup Flow section for readers who want the Console-only path instead
Verified against the SDK source (auth-connection.ts buildUpdateMask and the auth-connection.test.ts CI-scenario tests): once a connection is already deployed, an empty clientSecret is excluded from the update mask entirely, leaving the stored secret untouched. This only applies to updates of an existing connection — the initial create still requires the real secret. Also note that the field must be an explicit empty string, not undefined, since the config schema requires a string.
process.env.X! only silences TypeScript; if the var is actually unset at runtime, clientSecret stays undefined and AuthConfigSchema.parse still throws. process.env.X ?? "" is the pattern that actually produces a string in that case.
anukiransolur
approved these changes
Jul 2, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/guides/auth/authconnection.md) to configure and manage connections through the SDK (defineAuth()'sconnectionsfield +tailor-sdkCLI) instead oftailorctl, following sdk#1603 which madedeployupdate connections in-place and preserve the OAuth tokendocs/sdk/services/auth.mdfrom the SDK repo to pick up the same change (drops the stale delete-and-recreate warning and Change Detection section). This file is normally auto-synced by the dailysdk-docs-syncworkflow, but that job only runs againstmainand wouldn't catch up until after merge, so it's included here to keep the guide and the SDK reference consistent within this PRsetup-auth-connectionstutorial's info box to describe in-place updates instead of the old hash-based revoke/recreate behavior