---
title: "Start Slack Oauth"
method: POST
path: "/v3/integrations/slack/oauth/start"
tags: ["integrations-v3"]
---

# Start Slack Oauth

`POST /v3/integrations/slack/oauth/start`

## Request

- Base URL: `https://api.traversal.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.traversal.com/v3/integrations/slack/oauth/start`
- Auth: none declared

Begin an org-scoped "Add to Slack" install and return the authorize URL.

The signed-in user's org is stamped onto the OAuth state, so when the
Slack callback lands (on the slackbot host) the install is provisioned to
that org immediately — no admin link step. The frontend opens the returned
``authorization_url`` in a new tab.

The return origin comes from the request body (browsers omit the Origin
header on same-origin requests), falling back to the Origin header.

**Permissions**: integration setup user.

## Query parameters

- `organization_id` string, nullable

## Request body

- StartSlackOAuthRequest: Request body to begin a UI-initiated ("Add to Slack") install flow.
  - `return_url` string, nullable: Frontend origin to return the browser to after a successful install (e.g. window.location.origin). Validated against the allowed frontend origins; ignored if it doesn't match. Falls back to the Origin header.

## Response `201`

Successful Response

- StartSlackOAuthResponse: Result of starting a UI-initiated ("Add to Slack") install flow.
  - `authorization_url` string, required: Slack authorize URL the browser should navigate to (opened in a new tab).

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/traversal/apis/traversal-api.md) - [All operations](https://skmtc.dev/traversal/apis/traversal-api/llms.txt) - [OpenAPI document](https://skmtc.dev/traversal/apis/traversal-api/revisions/31e1a8b7cf89?raw)