> ## Documentation Index
> Fetch the complete documentation index at: https://darwin.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboard

> Create a destination-provider account without confusing registration with authentication or authority.

Onboard creates a new account with the destination provider when the selected capability cannot continue without one. It is separate from [Authenticate](/docs/act/connections), which grants access to an account that already exists.

<Note>
  `POST /actions/{actionId}/onboard` is a planned preview and is not callable in production yet. It will start a
  provider signup step when the Action offers `onboard`; it will not assert that signup succeeded.
</Note>

When an Action returns `onboarding_required`, call the planned [Onboard for action](/docs/reference/act-onboard) operation with its `interactionId`, `revision`, and an idempotent `requestId`. Darwin returns the current Action and a first-party `webLink`. The provider creates the account and confirms the result to Darwin; then the caller reads the same `actionId`. A client message saying “signup complete” never advances the Action by itself.

```json theme={null}
{
  "interactionId": "interaction_01J9Y8R5Y6W7K8M9N0P1Q2R3ST",
  "expectedRevision": 2,
  "requestId": "onboard-1042"
}
```

No profile fields, passwords, one-time codes, or consent claims belong in this request. The hosted flow shows the provider, required information, and terms before the user continues.

## Keep registration explicit

A signup flow can ask the user to provide required profile fields, review provider terms, choose communication preferences, and complete provider-owned eligibility steps. Darwin should show who receives each field and why before opening a first-party `webLink` or provider page.

```text theme={null}
onboarding required -> POST /actions/{actionId}/onboard -> first-party webLink
                    -> user reviews provider and required fields
                    -> provider creates account -> backend confirmation
                    -> same Action resumes or moves to Authenticate / Verify
```

## Separate the decisions

| Decision     | Meaning                                                             |
| ------------ | ------------------------------------------------------------------- |
| Onboard      | Create a new provider account under the reviewed terms.             |
| Authenticate | Grant bounded access to an existing account.                        |
| Verify       | Establish an email, phone, identity, age, business, or other claim. |
| Approve      | Authorize one exact consequential action.                           |
| Pay          | Complete one purchase under bound commercial terms.                 |

Finishing signup does not automatically grant Darwin reusable access, approve future work, authorize payment, or prove every provider requirement. The Action advances only after backend confirmation.

## Minimize collected data

* Request only fields the destination provider requires for the current account type.
* Keep passwords, one-time codes, recovery material, and identity evidence out of prompts and Action updates.
* Do not preselect marketing consent or bundle it with required terms.
* Explain whether the provider, Darwin, or both will retain each submitted field.
* Require a separate choice before saving any reusable credential in Darwin Vault.

Continue with [Onboard best practices](/docs/act/sign-up/best-practices) or [Authenticate](/docs/act/connections) when the account already exists.