> ## Documentation Index
> Fetch the complete documentation index at: https://bundleup.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authorize

> Start the authorization flow. Open this URL in the user’s browser.

Redirect the user’s browser to this URL to start connecting an account. BundleUp validates the parameters, then sends the user to the provider’s consent screen. When the flow finishes, the user is redirected to your `redirect_uri`.

This is a browser URL, not an API call: don’t send your API key, and don’t call it from your backend.

See [Connecting user accounts](/docs/guides/auth/authorization-flow) for the full flow.

## Query parameters

<ParamField query="client_id" type="string" required>
  Your workspace’s client ID, from **Auth** in the dashboard.
</ParamField>

<ParamField query="integration_id" type="string" required>
  The **identifier** of the integration to connect, for example `github`.
</ParamField>

<ParamField query="redirect_uri" type="string" required>
  Where to send the user when the flow ends. Must exactly match a redirect URI registered under **Auth**.
</ParamField>

<ParamField query="external_id" type="string">
  Your own reference for this connection, usually your user ID. Returned when you exchange the code, and included in webhooks.
</ParamField>

<ParamField query="state" type="string">
  Any value. Returned unchanged on the redirect to `redirect_uri`, on success and on error. Use a random value per flow to prevent CSRF.
</ParamField>

## Result

The user has 10 minutes to complete the flow. Then BundleUp redirects to `redirect_uri` with:

<ResponseField name="code" type="string">
  On success. A one-time code to [exchange for the connection ID](/docs/api-reference/auth/exchange-code). Expires after 5 minutes. Single use.
</ResponseField>

<ResponseField name="error" type="string">
  On failure. The provider’s error code (such as `access_denied`), or `invalid_request` (the provider returned no code) or `token_error` (the provider’s token exchange failed).
</ResponseField>

<ResponseField name="error_description" type="string">
  On failure. A human-readable description.
</ResponseField>

<ResponseField name="state" type="string">
  Your `state`, if you sent one.
</ResponseField>

If `client_id`, `integration_id` or `redirect_uri` is missing or invalid, BundleUp shows an error page and doesn’t redirect.

<RequestExample>
  ```text Authorization URL theme={null}
  https://auth.bundleup.io/authorize?client_id=YOUR_CLIENT_ID&integration_id=github&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&external_id=user_42&state=Rk3jX9
  ```
</RequestExample>

<ResponseExample>
  ```text Success redirect theme={null}
  https://app.example.com/callback?state=Rk3jX9&code=Yx8k2...
  ```

  ```text Error redirect theme={null}
  https://app.example.com/callback?state=Rk3jX9&error=access_denied&error_description=The+user+denied+access
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.