---
title: "Start a Stripe Connect authorization"
method: POST
path: "/companies/{company}/connected-accounts/authorizations"
tags: ["Stripe"]
---

# Start a Stripe Connect authorization

`POST /companies/{company}/connected-accounts/authorizations`

## Request

- Base URL: `https://api.factuarea.com/v1`
- URL: `https://api.factuarea.com/v1/companies/{company}/connected-accounts/authorizations`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Starts connecting a Stripe account to the company and returns the Stripe onboarding `url` (201, `status` `pending`).
- Needs `Idempotency-Key` and an `https` `return_url` on an allowed domain (`connect_return_url_not_allowed`).
- Live credentials only: test keys fail with 403 `live_credential_required`.
- No MCP tool: it needs a browser redirect.

## Path parameters

- `company` string, uuid, required

## Headers

- `Idempotency-Key` string, required
- `Factuarea-Version` string, date

## Request body

- StartConnectedAccountAuthorizationV1Request: Start the Stripe Connect authorization of a company. `return_url` is required: an absolute `https` URL (up to 2048 characters, no credentials, no fragment, port 443 or none) whose host is one of the return domains of the account of the credential. Any other key in the body or the query returns 400 `parameter_unknown`.
  - `return_url` string, uri, required: HTTPS URL the person is sent back to when Stripe finishes (up to 2048 characters). Its host must be one of the return domains of the account of the credential, otherwise the request returns 422 `connect_return_url_not_allowed`. Factuarea appends these query parameters on the way back: `status` (`success` or `error`), `provider` (always `stripe`) and `authorization_id` always; on success also `company_id` (the company `id`, UUID v7), `connected_account_id` and `account`; on error also `error` and, when there is one, `error_subcode`.

## Response `201`

The authorization was started. `data.url` is the Stripe link to open in the browser; `data.id` comes back as `authorization_id` in the redirect to your `return_url`. If a valid authorization of that company and account already existed it is reused: the same `id` and Stripe account come back with a fresh link. There is no `Location` header: the authorization has no individual read.

- object
  - `data` ConnectedAccountAuthorization, required: A Stripe Connect authorization in progress for one company. Open `url` in the browser of the person who owns the Stripe account; Factuarea completes the connection when Stripe sends them back and then redirects to `return_url`.
    - `id` string, uuid, required: Opaque identifier (UUID v7) of the authorization. It comes back as `authorization_id` in the redirect to `return_url`.
    - `object` 'connected_account_authorization', required: Always `connected_account_authorization`.
    - `url` string, uri, required: Stripe onboarding link to open in the browser. It is a short-lived Stripe Account Link: when it expires or has already been used, Stripe sends the person to the refresh URL of Factuarea, which renews it, so you do not need to start again. `expires_at` is not its expiry.
    - `return_url` string, uri, required: The `https` address the person is sent back to, exactly as you sent it.
    - `status` 'pending' | 'completed', required: `pending` until the person finishes in Stripe; a started authorization is always returned `pending`.
    - `expires_at` string, date-time, required: Deadline to complete the authorization (24 hours after it was started by default). After that instant the redirect to `return_url` reports an expired authorization and you must start it again. It is not the expiry of `url`.
    - `company_id` string, uuid, required: Public identifier (UUID v7) of the company the Stripe account will be connected to.

## Other responses

- `400`: `parameter_unknown` with `subcode` `retired_active_profile_header`: the retired `X-Active-Profile` header was sent; the company goes in the path. `parameter_invalid_format` on `Factuarea-Version`: the header is not a `YYYY-MM-DD` date. `unsupported_api_version`: the `Factuarea-Version` date is not a supported version.
- `401`: Missing or invalid API key.
- `403`: The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).
- `404`: The requested resource does not exist or belongs to another company. `profile_not_found`: the company in the path does not exist, is not in the API key scope or belongs to the other environment (live or test).
- `422`: Validation failed. The `error.param` field identifies which input is invalid.
- `429`: Rate limit exceeded. Retry after the duration in `Retry-After`.
- `500`: Unexpected server error.

---

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