---
title: "Start an authorization"
method: POST
path: "/v2/workspaces/{id}/connectors"
tags: ["Connectors"]
---

# Start an authorization

`POST /v2/workspaces/{id}/connectors`

## Request

- Base URL: `https://api.infolang.ai`
- URL: `https://api.infolang.ai/v2/workspaces/{id}/connectors`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer

Creates a `pending_auth` connection and returns `authorize_url` — send the human there. The provider redirects back to the gateway's `/connectors/callback`, which completes the exchange and bounces to the console at `/connectors?connected=<connection_id>`.

The URL carries a signed, expiring `state` handle binding this workspace and connection; it is valid for `authorize_expires_in` seconds and cannot be reused afterwards.

`409 provider_not_configured` means this DEPLOYMENT has no OAuth application registered with the provider (its client id/secret environment variables are unset). The provider is supported; an operator has not connected it yet. Read `providers[].configured` from `GET /v2/workspaces/{id}/connectors` and render an unconfigured provider as unavailable rather than letting a click fail.

Requires the `connectors:write` scope. Accepts all three lanes: a session JWT (bounded by the caller's role on this workspace) or an `il_*` machine credential whose own scope set, workspace set and validity window cover it — both ceilings apply and neither can raise the other, so a credential carrying `connectors:write` is still refused where the role does not permit it.

A credential with no scope record resolves to `LEGACY_DEFAULT`, which does NOT include `connectors:write` — mint a key with it explicitly (`POST /v2/workspaces/{id}/keys`).

## Path parameters

- `id` string, required

## Request body

- object
  - `provider` 'google_drive' | 'notion', required
  - `target_namespace` string, required

## Response `201`

The pending connection and the provider authorize URL

- object
  - `connection_id` string, required
  - `workspace_id` string, required
  - `provider` 'google_drive' | 'notion', required
  - `status` 'pending_auth' | 'active' | 'error' | 'revoked', required
  - `target_namespace` string, required
  - `source_scope` unknown
  - `synced_count` number, required
  - `created_at` string, required
  - `updated_at` string, required
  - `last_sync_at` string, nullable, required
  - `error` string, nullable, required
  - `authorize_url` string, required
  - `authorize_expires_in` number, required

## Other responses

- `401`: Missing/invalid credential, or `credential_expired` — the credential is outside its `[not_before, expires_at)` window and must be replaced
- `403`: `insufficient_scope` — the credential's own scope set, or the caller's role on this workspace, does not cover the scope this route requires (the missing scope is named in the message). Or `forbidden` — the credential is not scoped to this workspace, or holds no grant on it
- `409`: `provider_not_configured` — no OAuth application is registered for this provider on this deployment
- `422`: Unknown provider, or a namespace this credential cannot write

---

[API](https://skmtc.dev/infolang/apis/infolang-api.md) · [All operations](https://skmtc.dev/infolang/apis/infolang-api/llms.txt) · [OpenAPI document](https://skmtc.dev/infolang/apis/infolang-api/revisions/d04bf6de72c8?raw)