---
title: "Authorize"
method: POST
path: "/api/v1/integrations/{provider}/authorize"
tags: ["integrations"]
---

# Authorize

`POST /api/v1/integrations/{provider}/authorize`

## Request

- Base URL: `https://api.aws.cognee.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.aws.cognee.ai/api/v1/integrations/{provider}/authorize`
- Auth: API key in header `X-Api-Key`

Mint the provider's install URL for a tenant owner.

``nonce_hash`` binds this state to one browser: the caller has already
put the raw nonce in that browser's hands, on its own origin, and only
that browser can produce it again at completion (#373 bot review,
module docstring on ``flow.py``). Without the binding a state minted
here would be valid for *any* browser that later presents it.

The hash arrives from the caller rather than being generated here
because the cookie has to be set by a response the browser actually
receives, which is the frontend's, not this service's (CLO-890).

``fresh_account`` is the caller's own declaration that this attempt is
for a genuinely *different* account (CLO-528's "Connect another
{provider} account"), not a plain reconnect of the tenant's existing
one. Without it, this route always targets the tenant's *latest*
credential row for the provider — right for the common case (one
Connect button, transparently reconnecting whatever this tenant last
held), wrong for this one: a tenant disconnecting org B and clicking
Connect again, or explicitly asking to add a second org, would
otherwise be silently routed back to managing or reactivating org B,
with no way to reach a fresh install picker for anything else while
that installation still exists (review-reported).

``link_existing`` asks for a connector's "link an existing
installation" OAuth leg (:meth:`CloudConnector.link_url`) instead of
its normal install URL (:meth:`CloudConnector.authorize_url`), which
is GitHub's product default for Connect and Connect-another since
CLO-627, because an install URL can silently strand ``state`` the
moment the chosen account already has the app installed (see the
GitHub connector's own ``authorize_url`` docstring), while the OAuth
leg always calls back with ``code`` and ``state`` regardless. 400 for
a connector that has not opted into
:data:`CloudConnector.supports_link_existing`, every connector but
GitHub today. When set, this skips the existing-row lookup and
reactivation below entirely: linking is not "reconnect my latest
row" by definition, it is the tenant owner picking from whatever the
OAuth code proves access to on ``POST /{provider}/complete`` and
``/link``, including picking a row this tenant already holds, or one
it previously revoked, or a different org altogether. ``fresh_account``
has no effect when this is set, for the same reason: the lookup it
would otherwise skip already never runs here. The install URL stays
reachable, via ``fresh_account`` alone, for the one thing linking
cannot do: installing the app on an organization it is not on yet.

## Path parameters

- `provider` string, required

## Query parameters

- `tenant_id` string, uuid, required
- `nonce_hash` string, nullable
- `fresh_account` boolean
- `link_existing` boolean

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

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