> ## 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.

# Exchange a Code

> Turn the one-time code from the authorization redirect into a connection ID.

Call this from your backend after the user lands on your `redirect_uri` with a `code`. It returns the new connection’s ID.

The code expires **5 minutes** after it’s issued and can be used **once**.

## Headers

<ParamField header="Authorization" type="string" required>
  `Bearer YOUR_API_KEY`. Must be a key from the same workspace that issued the code.
</ParamField>

## Body

<ParamField body="code" type="string" required>
  The `code` query parameter from the redirect.
</ParamField>

<ParamField body="redirect_uri" type="string" required>
  The exact `redirect_uri` used to start the flow.
</ParamField>

## Response

<ResponseField name="connection_id" type="string">
  The new connection’s ID. Store it, and send it as `BU-Connection-Id` on requests.
</ResponseField>

<ResponseField name="external_id" type="string | null">
  The `external_id` passed when starting the flow, or `null`.
</ResponseField>

<ResponseField name="integration_id" type="string">
  The integration’s **identifier**, for example `github`.
</ResponseField>

## Errors

* `400` with `errors.code`: the code has expired, was already used, was issued for a different `redirect_uri`, or belongs to another workspace.
* `400` with `errors.redirect_uri` or `errors.code`: the field is missing.
* `401`: the API key is missing or not recognized.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://auth.bundleup.io/connection \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"code": "Yx8k2...", "redirect_uri": "https://app.example.com/callback"}'
  ```

  ```typescript JavaScript theme={null}
  const { connection_id } = await client.auth.getConnectionFromCode({
    code,
    redirectUri: 'https://app.example.com/callback',
  });
  ```

  ```python Python theme={null}
  connection = client.auth.get_connection_from_code(
      code=code,
      redirect_uri="https://app.example.com/callback",
  )
  ```

  ```ruby Ruby theme={null}
  connection = client.auth.get_connection_from_code(
    code: code,
    redirect_uri: 'https://app.example.com/callback'
  )
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "connection_id": "conn_abc123",
    "external_id": "user_42",
    "integration_id": "github"
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "message": "Invalid request",
    "errors": {
      "code": ["Invalid or expired authorization code"]
    }
  }
  ```

  ```json 401 theme={null}
  {
    "success": false,
    "message": "Not authorized"
  }
  ```
</ResponseExample>


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