# Connect an app with one click

> Let the people who use your app connect their VocalStack account with one Authenticate click — OAuth 2.0 authorization code with PKCE, where the access token is an API key — instead of pasting a key.

| Endpoint | What it does |
|---|---|
| `POST /v1/connect/token` | Redeem a connect code |
| `GET /v1/me` | Get the current account |

If your app runs on your users' own servers (a CMS plugin, a self-hosted tool), each of them needs an API key for their own VocalStack account. One-click Connect gets it for them: your app opens VocalStack's dashboard, the person signs in and clicks **Authenticate**, and your server receives a key named after your app. Nobody copies a key, and the key never passes through a browser.

It is OAuth 2.0's authorization code flow with PKCE (RFC 7636, `S256` only), and the access token it issues is an ordinary API key. There is nothing to register: the consent screen shows the person the host of your `redirect_uri`, so they can tell whose server will hold the key.

1. You → VocalStack: `open {dashboard}/connect?response_type=code&client_name=…&redirect_uri=…&state=…&code_challenge=…&code_challenge_method=S256&scope=read write` (in a new tab)
2. VocalStack → you: `the consent screen: sign in, pick the workspace, Authenticate` (owners and admins only)
3. VocalStack → you: `redirect_uri?code=…&state=…` (or ?error=access_denied&state=… on Cancel)
4. You → VocalStack: `POST /v1/connect/token  grant_type=authorization_code, code, code_verifier, redirect_uri` (from your server)
5. VocalStack → you: `{ access_token: "vs_key_…", token_type: "api_key", key_id, scope, reach, account: { name }, workspace: { id, name, personal, iconUrl } }`

## 1. Send the person to the consent screen

Make a random `state` and a PKCE verifier (43 to 128 characters of `A-Z a-z 0-9 - . _ ~`; 32 or more random bytes, base64url-encoded, are right), keep both on your server for a few minutes, and open the dashboard's `/connect` page with:

| Parameter | Value |
|---|---|
| `response_type` | `code` |
| `client_name` | Your app as the person will recognise it, at most 100 characters: `drbc.org (Payload CMS)`. The key is named after it. |
| `redirect_uri` | Where the dashboard sends the browser back to: absolute `https`, or `http` for `localhost` / `127.0.0.1` while you develop. No fragment. |
| `state` | Your random value; it comes back unchanged. |
| `code_challenge` | `BASE64URL(SHA256(verifier))`, without padding (43 characters). |
| `code_challenge_method` | `S256` |
| `scope` | `read`, `write` or `read write`. `write` is enough to transcribe files and links and to open realtime sessions. An app on the person's computer (a `localhost` / `127.0.0.1` redirect) may add `recordings:publish`, with `write`, to start and stop live transcriptions. Keys with full access, or a web app's key with `recordings:publish`, are made by hand in the dashboard. |
| `reach` | Optional. `own` (the default with `write`): the key reaches only what your app creates with it, its transcriptions and broadcasts and everything in them; the account's other ones answer `404`. `account`: everything on the account, whoever made it (the default, and the only reach, without `write`). |
| `workspace` | Optional. The `id` of the workspace your app is connected to now (`workspace.id` from the token answer or `GET /v1/me`): the consent screen starts on it when the person connects again to change workspace. Anything else is ignored, and the person can still pick another. |

A link that breaks a rule gets an error page and never redirects, so check it while you build.

## 2. The person authenticates

The dashboard asks the person to sign in if they are not, then shows your `redirect_uri`'s host (and whether it is https or a site on their own computer), the name you sent (marked as not checked), the account the key will act for — they choose when they belong to several — what the scopes allow and what the key reaches. Only owners and admins of an organization can connect an app to it.

**Authenticate** sends the browser to `redirect_uri?code=…&state=…`. **Cancel** sends it to `redirect_uri?error=access_denied&state=…`. Either way, check `state` against the one you kept before you do anything else.

## 3. Redeem the code on your server

Within two minutes, post the code with the verifier and the same `redirect_uri` to `POST /v1/connect/token`, form-encoded, from your server. No API key is needed: the code and its verifier are the proof. The answer carries the key (`access_token`), its id, the granted `scope`, its `reach` and the `workspace` the person picked (its `id`, `name`, whether it is their `personal` one, and `iconUrl`); store the key as you would one your user pasted. It is shown once, in this answer.

A code works once. A second redemption, a wrong verifier, a different `redirect_uri` or an expired code answers `400` with `{"error": "invalid_grant", "error_description": "…"}` (and spends the code); a missing or repeated parameter is `invalid_request`, any `grant_type` but `authorization_code` is `unsupported_grant_type`. A request from a web page is refused: keys are for servers.

## 4. Afterwards

The key is listed in Developers → API keys under your `client_name`, marked as a connected app, where the person can revoke it. Use it like any key: `GET /v1/me` says who it is and names its `workspace` again, so a rename or a new icon reaches your app. A key belongs to one workspace: everything it makes lands there and is billed there, and to work in another workspace the person connects again and picks it. `workspace.iconUrl` is the workspace's own icon (a PNG), a link relative to the API's address that needs no key; it is null when the workspace has none. Connecting again makes a new key and leaves the old one working until it is revoked, so revoke the key you replace, or let the person do it. An app that streams to the account over RTMP makes a stream key of its own with `POST /v1/rtmp/keys`; it works while the app's key does, so revoking the app stops its stream too.

## Complete code

Each program runs as it is once `VOCALSTACK_API_KEY` holds one of your API keys.

### TypeScript SDK: `connect.ts`

```typescript
import { createHash, randomBytes } from 'node:crypto';
import { VocalStack } from '@vocalstack/js-sdk';

const DASHBOARD = process.env.VOCALSTACK_DASHBOARD_URL ?? 'https://app.vocalstack.com';
const REDIRECT_URI = 'https://example.com/api/vocalstack/callback';
// One sign-in in flight; keep these in your session store instead.
const pending = new Map<string, string>();

export function connectUrl(): string {
  const state = randomBytes(24).toString('base64url');
  const verifier = randomBytes(48).toString('base64url');
  pending.set(state, verifier);
  const url = new URL('/connect', DASHBOARD);
  url.search = new URLSearchParams({
    response_type: 'code',
    client_name: 'example.com (My CMS)',
    redirect_uri: REDIRECT_URI,
    state,
    code_challenge: createHash('sha256').update(verifier).digest('base64url'),
    code_challenge_method: 'S256',
    scope: 'read write',
  }).toString();
  return url.toString();
}

export async function callback(query: URLSearchParams): Promise<string> {
  const verifier = pending.get(query.get('state') ?? '');
  pending.delete(query.get('state') ?? '');
  if (!verifier) throw new Error('unknown or reused state');
  if (query.get('error')) throw new Error(`not connected: ${query.get('error')}`);

  const vs = new VocalStack({ baseUrl: 'https://api.vocalstack.com' });
  const token = await vs.connect.token({ code: query.get('code') ?? '', codeVerifier: verifier, redirectUri: REDIRECT_URI });
  console.log(`connected to ${token.workspace.name} (${token.scope})`);

  const me = await new VocalStack({ baseUrl: 'https://api.vocalstack.com', apiKey: token.access_token }).me.get();
  console.log(me.apiKeyId === token.key_id);
  return token.access_token;
}
```

### Python SDK: `connect.py`

```python
import base64
import hashlib
import os
import secrets
from urllib.parse import urlencode

from vocalstack import VocalStack

DASHBOARD = os.environ.get("VOCALSTACK_DASHBOARD_URL", "https://app.vocalstack.com")
REDIRECT_URI = "https://example.com/api/vocalstack/callback"
# One sign-in in flight; keep these in your session store instead.
pending: dict[str, str] = {}


def connect_url() -> str:
    state = secrets.token_urlsafe(24)
    verifier = secrets.token_urlsafe(48)
    pending[state] = verifier
    challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).rstrip(b"=").decode()
    return f"{DASHBOARD}/connect?" + urlencode({
        "response_type": "code",
        "client_name": "example.com (My CMS)",
        "redirect_uri": REDIRECT_URI,
        "state": state,
        "code_challenge": challenge,
        "code_challenge_method": "S256",
        "scope": "read write",
    })


async def callback(query: dict[str, str]) -> str:
    verifier = pending.pop(query.get("state", ""), None)
    if verifier is None:
        raise RuntimeError("unknown or reused state")
    if "error" in query:
        raise RuntimeError(f"not connected: {query['error']}")

    async with VocalStack("https://api.vocalstack.com") as vs:
        token = await vs.connect.token(code=query.get("code", ""), code_verifier=verifier, redirect_uri=REDIRECT_URI)
    print(f"connected to {token['workspace']['name']} ({token['scope']})")

    async with VocalStack("https://api.vocalstack.com", api_key=token["access_token"]) as vs:
        me = await vs.me.get()
        print(me["apiKeyId"] == token["key_id"])
    return token["access_token"]
```

### PHP SDK: `connect.php`

```php
<?php
// Two handlers of your web app: connectUrl() behind its Connect button,
// callback() at REDIRECT_URI. The verifier waits in the person's session.
require 'vendor/autoload.php';

use VocalStack\Connect\Pkce;
use VocalStack\VocalStack;

define('DASHBOARD', getenv('VOCALSTACK_DASHBOARD_URL') ?: 'https://app.vocalstack.com');
const REDIRECT_URI = 'https://example.com/api/vocalstack/callback';
session_start();

function connectUrl(): string
{
    $state = Pkce::state();
    $verifier = Pkce::verifier();
    $_SESSION['vocalstack'][$state] = $verifier;
    return DASHBOARD . '/connect?' . http_build_query([
        'response_type' => 'code',
        'client_name' => 'example.com (My CMS)',
        'redirect_uri' => REDIRECT_URI,
        'state' => $state,
        'code_challenge' => Pkce::challenge($verifier),
        'code_challenge_method' => 'S256',
        'scope' => 'read write',
    ], encoding_type: PHP_QUERY_RFC3986);
}

function callback(array $query): string
{
    $state = $query['state'] ?? '';
    $verifier = $_SESSION['vocalstack'][$state] ?? null;
    unset($_SESSION['vocalstack'][$state]);
    if ($verifier === null) {
        throw new RuntimeException('unknown or reused state');
    }
    if (isset($query['error'])) {
        throw new RuntimeException("not connected: {$query['error']}");
    }

    $vs = new VocalStack(baseUrl: 'https://api.vocalstack.com');
    $token = $vs->connect->token(code: $query['code'] ?? '', codeVerifier: $verifier, redirectUri: REDIRECT_URI);
    echo "connected to {$token['workspace']['name']} ({$token['scope']})\n";

    $vs = new VocalStack(apiKey: $token['access_token'], baseUrl: 'https://api.vocalstack.com');
    $me = $vs->me->get();
    echo $me['apiKeyId'] === $token['key_id'] ? 'true' : 'false', "\n";
    return $token['access_token'];
}
```

### HTTP + WebSocket: `connect.sh`

```bash
#!/usr/bin/env bash
# curl, openssl and jq, no SDK.
set -euo pipefail
API=https://api.vocalstack.com
DASHBOARD=${VOCALSTACK_DASHBOARD_URL:-https://app.vocalstack.com}
REDIRECT_URI=https://example.com/api/vocalstack/callback

STATE=$(openssl rand -base64 24 | tr '+/' '-_' | tr -d '=')
VERIFIER=$(openssl rand -base64 48 | tr '+/' '-_' | tr -d '=\n')
CHALLENGE=$(printf %s "$VERIFIER" | openssl dgst -sha256 -binary | openssl base64 | tr '+/' '-_' | tr -d '=')
echo "Open: $DASHBOARD/connect?response_type=code&client_name=My%20script&redirect_uri=$(jq -rn --arg u "$REDIRECT_URI" '$u|@uri')&state=$STATE&code_challenge=$CHALLENGE&code_challenge_method=S256&scope=read%20write"

read -rp "Paste the code from the address you were sent back to: " CODE

TOKEN=$(curl -sS "$API/v1/connect/token" \
  --data-urlencode grant_type=authorization_code \
  --data-urlencode "code=$CODE" \
  --data-urlencode "code_verifier=$VERIFIER" \
  --data-urlencode "redirect_uri=$REDIRECT_URI")
jq '{token_type, key_id, scope, account, error, error_description}' <<<"$TOKEN"

curl -sSf "$API/v1/me" -H "Authorization: Bearer $(jq -r .access_token <<<"$TOKEN")" | jq '{principalId, apiKeyId, scopes}'
```


---

All guides: https://api.vocalstack.com/llms.txt. Every operation: https://api.vocalstack.com/llms-full.txt. The OpenAPI document, with every WebSocket frame under `x-websocket`: https://api.vocalstack.com/v1/openapi.json.
