---
title: "OAuth and OAuth apps"
description: "Start the interactive OAuth flow and manage your BYOK OAuth app configs."
section: "API reference"
url: https://dravo.dev/docs/api/oauth
---
# OAuth and OAuth apps

OAuth connects an account interactively, while OAuth apps hold your BYOK
credentials per provider. Background: [BYOK](/docs/concepts/byok).

## Start the OAuth flow

Returns the provider authorize URL; redirect the user there. After consent the
provider calls Dravo's callback and the account is connected. The callback is
handled by Dravo and needs no auth (the state is signed).

#### `GET /v1/oauth/{provider}/start`

Get the provider authorize URL to redirect the user into the OAuth consent screen.

**Auth:** Dashboard JWT only

| Field | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `provider` | path | string | yes | instagram | facebook | x | linkedin | tiktok. |
| `oauth_app_id` | query | string | no | Use a specific BYOK OAuth app; omit for the default. |

Response `200`: Authorize URL.

```json
{
  "authorize_url": "https://www.tiktok.com/v2/auth/authorize/?client_key=…"
}
```


## List OAuth apps

Each app shows the `redirect_uri` you must register on the provider and the
`scopes` Dravo will request. Secrets are never returned.

#### `GET /v1/oauth-apps`

List your BYOK OAuth app configs. Includes the redirect_uri to register and the scopes Dravo will request.

**Auth:** Dashboard JWT only

| Field | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `provider` | query | string | no | Filter by provider. |

Response `200`: OAuth apps.

```json
[
  {
    "id": "oa_1",
    "provider": "x",
    "name": "My X App",
    "client_id": "…",
    "redirect_uri": "https://api.dravo.dev/v1/oauth/x/callback",
    "scopes": [
      "tweet.write",
      "media.write",
      "users.read",
      "offline.access"
    ]
  }
]
```


## Create an OAuth app

Store your own `client_id` and `client_secret` for a provider. The secret is
encrypted at rest.

#### `POST /v1/oauth-apps`

Create a BYOK OAuth app config (your client_id/client_secret). The secret is encrypted and never returned.

**Auth:** Dashboard JWT only

| Field | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `provider` | body | string | yes | instagram | facebook | x | linkedin | tiktok. |
| `name` | body | string | yes | 1 to 120 chars. |
| `client_id` | body | string | yes | Your app's client id / client key. |
| `client_secret` | body | string | yes | Your app's client secret (stored encrypted). |

Request:

```json
{
  "provider": "x",
  "name": "My X App",
  "client_id": "…",
  "client_secret": "…"
}
```

Response `201`: Created.

```json
{
  "id": "oa_1",
  "provider": "x",
  "redirect_uri": "https://api.dravo.dev/v1/oauth/x/callback",
  "scopes": [
    "tweet.write",
    "media.write"
  ]
}
```