Tornevall Networks

← Back to docs

OAuth Endpoints

Language: EN | EN | SV

OAuth Endpoints

This page documents OAuth endpoints used by Tools web integrations.

Slack OAuth

Start OAuth flow

  • Route name: oauth.slack.start
  • Path: /oauth/slack/start
  • Method: GET or POST
  • Auth: auth:web

Starts the Slack OAuth flow and redirects to Slack oauth/v2/authorize.

OAuth callback

  • Route name: oauth.slack.callback
  • Path: /oauth/slack/callback
  • Method: GET
  • Auth: auth:web

Slack redirects back here with code and state.

Callback URL helper

  • Route name: oauth.slack.callback-url
  • Path: /oauth/slack/callback-url
  • Method: GET
  • Auth: auth:web

Returns the currently computed callback URL in JSON:

{
  "callback_url": "https://tools.tornevall.com/oauth/slack/callback"
}

SoundCloud OAuth

Start OAuth flow

  • Route name: oauth.soundcloud.start
  • Path: /oauth/soundcloud/start
  • Method: POST
  • Auth: auth:web

Expected payload:

{
  "provider_app_id": 1,
  "target_owner_type": "system",
  "target_owner_id": null
}

OAuth callback

  • Route name: oauth.soundcloud.callback
  • Path: /oauth/soundcloud/callback
  • Method: GET
  • Auth: auth:web

Receives provider callback values (state, code, error, error_description).

Microsoft OAuth (shared Microsoft Graph app)

Start OAuth flow

  • Preferred route name: oauth.microsoft.start
  • Preferred path: /oauth/microsoft/start
  • Legacy compatibility route name: oauth.microsoft_todo.start
  • Legacy compatibility path: /oauth/microsoft-todo/start
  • Method: POST
  • Auth: auth:web

Starts the shared Microsoft OAuth flow for the currently logged-in user.

Direct auth-start link

  • Preferred route name: oauth.microsoft.start_link
  • Preferred path: /oauth/microsoft/start-link
  • Legacy compatibility route name: oauth.microsoft_todo.start_link
  • Legacy compatibility path: /oauth/microsoft-todo/start-link
  • Method: GET
  • Auth: auth:web

Creates a fresh signed Microsoft OAuth state and redirects directly to Microsoft from one normal clickable browser URL.

OAuth callback

  • Preferred route name: oauth.microsoft.callback
  • Preferred path: /oauth/microsoft/callback
  • Legacy compatibility route name: oauth.microsoft_todo.callback
  • Legacy compatibility path: /oauth/microsoft-todo/callback
  • Method: GET
  • Auth: public callback URL (the signed OAuth state still decides which user/transaction may finish)

Receives provider callback values (state, code, error, error_description) and stores the current per-user Microsoft connection used by Microsoft To Do today. When the original browser session is gone, Tools now recreates the matching web session from the signed OAuth state before redirecting the user back into the Microsoft To Do integration page.

API OAuth start helper

  • Primary path: /api/microsoft/oauth/start
  • Legacy compatibility path: /api/microsoft-todo/oauth/start
  • Method: GET
  • Auth: logged-in web session or JWT bearer token from POST /api/account/login

Returns one Microsoft authorization URL for the authenticated user together with the callback URL currently expected by this host.

Generic Microsoft auth status helper

  • Path: /api/microsoft/auth/status
  • Method: GET
  • Auth: logged-in web session or JWT bearer token from POST /api/account/login

Returns the shared Microsoft auth/platform-app readiness for the authenticated user, including callback/start URLs and tenant/account-type diagnostics that are not tied only to Microsoft To Do list/task counts.

X callback placeholder

The current X mention-bot does not complete a browser-based OAuth exchange. It still uses static server-side X_BOT_* credentials from .env.

If you receive X OAuth 2.0 client credentials during app setup, store them in:

  • X_OAUTH2_CLIENT_ID
  • X_OAUTH2_CLIENT_SECRET
  • optional X_OAUTH2_REDIRECT_URI

If the X dashboard also shows generated OAuth 2.0 user tokens, store them in:

  • X_OAUTH2_ACCESS_TOKEN
  • X_OAUTH2_REFRESH_TOKEN

Those are reserved for a future callback-driven OAuth2 flow and are separate from the current OAuth1-style posting credentials X_BOT_ACCESS_TOKEN and X_BOT_ACCESS_TOKEN_SECRET.

However, Tools now exposes a public callback placeholder so there is a real URL available for X app registration when a callback field is required:

Callback placeholder

  • Route name: oauth.x.callback
  • Path: /oauth/x/callback
  • Method: GET
  • Auth: public

This route currently acts as an informational landing page and placeholder only. It does not yet exchange or store X OAuth tokens.

Callback URL helper

  • Route name: oauth.x.callback-url
  • Path: /oauth/x/callback-url
  • Method: GET
  • Auth: public

Returns JSON containing the currently computed X callback URL.

Redirect URL guidance

For Slack app configuration, use:

  • Dev: https://tools.tornevall.com/oauth/slack/callback
  • Prod: https://tools.tornevall.net/oauth/slack/callback

If SLACK_REDIRECT_URI is configured, that value is used as the effective redirect URI and should be registered in Slack App settings.

For the shared Microsoft / Microsoft Graph app configuration, register the callback matching the current environment:

  • Dev: https://tools.tornevall.com/oauth/microsoft/callback
  • Prod: https://tools.tornevall.net/oauth/microsoft/callback

Legacy callback aliases under /oauth/microsoft-todo/callback still work, but the generic /oauth/microsoft/callback route is now the recommended registration target for one shared Microsoft / Graph app that may later also serve broader integrations such as Microsoft Copilot-style flows.

If MICROSOFT_REDIRECT_URI is configured, that value becomes the effective redirect URI and should be registered in the Microsoft Entra app as well. Legacy MICROSOFT_TODO_REDIRECT_URI is still accepted as a compatibility alias.

If you expect personal Microsoft accounts (@outlook.com, @hotmail.com, @live.com), use tenant common or consumers and make sure the Azure app registration itself is enabled for personal accounts (MSA). If not, Microsoft commonly responds with unauthorized_client.

For X app registration, if you need a callback URL field even though the current bot uses static credentials, use:

  • Dev: https://tools.tornevall.com/oauth/x/callback
  • Prod: https://tools.tornevall.net/oauth/x/callback

When the Microsoft To Do platform app is not environment-managed, the shared app settings can now also be saved from /settings/integrations/microsoft-todo by an acknowledged admin. The page shows the same recommended callback URL together with additive diagnostics about missing platform-app fields.