Add Slack as a social connection
Before you start
Enabling OAuth with Slack allows your users to sign up and sign in to your Clerk app with their Slack account.
Configure for your development instance
For development instances, Clerk uses preconfigured shared OAuth credentials and redirect URIs—no other configuration is needed.
- In the Clerk Dashboard, navigate to the SSO connections page.
- Select Add connection and select For all users.
- Select Slack from the provider list.
Configure for your production instance
For production instances, you must provide custom credentials.
Keep two browser tabs open during setup: one for the Clerk Dashboard and one for Slack's API Platform.
Enable Slack as a social connection in Clerk
- In the Clerk Dashboard, navigate to the SSO connections page.
- Select Add connection and select For all users.
- Select Slack from the provider list.
- Ensure that both Enable for sign-up and sign-in and Use custom credentials are toggled on.
- Save the Redirect URL somewhere secure. Keep this page open.
Create a Slack app
- In the Slack API Platform, navigate to the Your Apps page and select Create New App.
- The Create an app modal will open. Depending on your app needs, select either From a manifest or From scratch. For more information on which to choose, refer to Slack's doc on manifests.
- After following the respective steps for either option, you'll be redirected to the App Credentials page. Save the Client ID and Client Secret somewhere secure. Keep this page open.
- In the sidenav, navigate to the OAuth & Permissions page.
- Scroll down to the Redirect URLs section and select Add New Redirect URL. Paste the Redirect URL you saved from the Clerk Dashboard. Select Add, then select Save URLs.
Set the Client ID and Client Secret in the Clerk Dashboard
- Navigate back to the Clerk Dashboard where the configuration page should still be open. Paste the Client ID and Client Secret values that you saved into the respective fields.
- Select Save.
Test your connection
The simplest way to test your connection is to visit your Clerk app's Account Portal, which is available for all Clerk apps out-of-the-box.
- In the Clerk Dashboard, navigate to the Account Portal page.
- Next to Sign-in, select the button to visit the sign-in page. The URL should resemble:
- For development -
https://your-domain.accounts.dev/sign-in - For production -
https://accounts.your-domain.com/sign-in
- For development -
- Sign in with your connection's credentials.
If sign-in fails, check Application Logs for an oauth_callback.failed event. Its details include the failure reason and may include an error message.
Once you confirm the connection, get the user's OAuth access token from your backend using the getUserOauthAccessToken() method to retrieve their data from the social provider.
Suggest a Slack workspace in a custom flow
To suggest a workspace for one sign-in or sign-up authorization attempt, pass slackTeamIdHint with strategy: 'oauth_slack'. Use a workspace ID that starts with T, followed by one or more uppercase letters or digits, such as T012ABCDEF. Clerk rejects an invalid ID, or a hint passed with any other strategy.
Clerk passes the value as Slack's team parameter. It's a hint only: it doesn't enforce workspace membership or restrict access to your application. Clerk doesn't save the value, so pass it on each attempt that needs it.
With the Core 3 JavaScript API, use signIn.sso() or signUp.sso():
const { error } = await signIn.sso({
strategy: 'oauth_slack',
slackTeamIdHint: 'T012ABCDEF',
redirectCallbackUrl: '/sso-callback',
redirectUrl: '/dashboard',
})
if (error) {
console.error(JSON.stringify(error, null, 2))
}Handle the returned error as described in the custom flow error handling guide. For callback route setup, see the Core 3 custom OAuth flow guide. Use redirectCallbackUrl for the callback route and redirectUrl for the destination after authentication. To use a popup, pass an open Window as popup and set redirectCallbackUrl to an absolute URL, such as new URL('/sso-callback', window.location.origin).href.
With the legacy JavaScript API, use signIn.authenticateWithRedirect() or signUp.authenticateWithRedirect():
await signIn.authenticateWithRedirect({
strategy: 'oauth_slack',
slackTeamIdHint: 'T012ABCDEF',
redirectUrl: '/sso-callback',
redirectUrlComplete: '/dashboard',
})Configure the callback route as described in the legacy custom OAuth flow guide. The legacy authenticateWithPopup() methods accept the same hint. Pass an open Window as popup and set redirectUrl to an absolute callback URL, such as new URL('/sso-callback', window.location.origin).href.
The Core 3 signIn.create() method and the legacy low-level signIn.create(), signUp.create(), signUp.update(), and signUp.prepareVerification() methods also accept slackTeamIdHint to start a Slack authorization attempt.
Feedback
Last updated on