> This page is for version v1.3 (default).
> For other versions, use one of these documentation indexes:
> - v1.3 (default): https://docs.twelvelabs.io/v1.3/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.twelvelabs.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.twelvelabs.io/_mcp/server.

# Authorize a connection

POST https://api.twelvelabs.io/v1.3/connections:authorize
Content-Type: application/json

This method starts the OAuth authorization flow for a data connector. The platform returns an authorization URL. Redirect the user to this URL so they can grant access to their account.

After the user grants or denies access, the platform redirects them to the redirect URI you provided, with the outcome appended to that URI as query parameters. Read these parameters from the redirect that your application receives:

- `connection_id`: The identifier of the new connection, returned on success. Store this value and pass it as the `connection_id` path parameter in later requests.
- `status`: The `ok` value, returned on success.
- `custom_id`: The label you supplied, returned on success when you provided one.
- `error`: An error code, returned instead of the other parameters when the user denies access or the flow fails.


Reference: https://docs.twelvelabs.io/api-reference/data-connectors/authorize-a-connection

## Authentication

- `x-api-key` header (required) — Your API key. You can find your API key on the API Keys page.

## Request

### Body (application/json)

This endpoint expects an object.

- `provider` (enum, required) — The data connector provider to authorize.
  - Allowed values: `google_drive`
- `redirect_uri` (string, required) — The URI where the user is redirected after granting or denying access. By default, any redirect URI is accepted. If you've authorized specific redirect URIs with the [Register a redirect URI](/v1.3/api-reference/data-connectors/register-a-redirect-uri) method, this URI must be one of them.
- `custom_id` (string, optional) — A label you supplied, stored on the connection and returned with it. Use a value that does not identify a person so you can match the connection to your own records.

## Response

### 200

The authorization flow has been successfully initiated.

- `authorize_url` (string, optional) — The URL to redirect the user to so they can grant access.
- `state` (string, optional) — A value the platform uses to secure the authorization flow. You do not need to read or send it: the platform includes it in the `authorize_url` field and checks it automatically when the user is redirected back. It is returned only so you can match or troubleshoot requests.

## Errors

### 400 Bad Request Error

The request has failed.

- `code` (string, optional) — A string representing the code associated with the error. See the [Error codes](/v1.3/api-reference/error-codes) page for details.
- `message` (string, optional) — A human-readable string describing the error, intended to be suitable for display in a user interface.

## Examples

**Request**

```json
{
  "provider": "google_drive",
  "redirect_uri": "https://app.example.com/oauth/done"
}
```

**Response**

```json
{
  "authorize_url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&state=...",
  "state": "eyJ1IjoiVVNFUiIsIm5vbmNlIjoiLi4uIn0"
}
```

**SDK Code**

```python
import requests

url = "https://api.twelvelabs.io/v1.3/connections:authorize"

payload = {
    "provider": "google_drive",
    "redirect_uri": "https://app.example.com/oauth/done"
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.twelvelabs.io/v1.3/connections:authorize';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"provider":"google_drive","redirect_uri":"https://app.example.com/oauth/done"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.twelvelabs.io/v1.3/connections:authorize"

	payload := strings.NewReader("{\n  \"provider\": \"google_drive\",\n  \"redirect_uri\": \"https://app.example.com/oauth/done\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.twelvelabs.io/v1.3/connections:authorize")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"provider\": \"google_drive\",\n  \"redirect_uri\": \"https://app.example.com/oauth/done\"\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.twelvelabs.io/v1.3/connections:authorize")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"provider\": \"google_drive\",\n  \"redirect_uri\": \"https://app.example.com/oauth/done\"\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.twelvelabs.io/v1.3/connections:authorize', [
  'body' => '{
  "provider": "google_drive",
  "redirect_uri": "https://app.example.com/oauth/done"
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.twelvelabs.io/v1.3/connections:authorize");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"provider\": \"google_drive\",\n  \"redirect_uri\": \"https://app.example.com/oauth/done\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "provider": "google_drive",
  "redirect_uri": "https://app.example.com/oauth/done"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/connections:authorize")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```