Connect API quickstart - Darwin

1. Register an application

curl https://api.darwin.so/api/v1/applications \
  --request POST \
  --header "Authorization: Bearer $DARWIN_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Acme Workspace",
    "websiteUrl": "https://app.acme.example",
    "redirectUris": ["https://app.acme.example/auth/darwin/callback"],
    "defaultAgentKind": "PERSONAL",
    "defaultVisibility": "PRIVATE"
  }'

Use exact HTTPS redirect URIs in production. Wildcards are rejected.

2. Choose identity

Use Sign in with Darwin when the user should own durable work, wallet activity, skills, or provider connections.
Use an Ephemeral Goal when your app funds one bounded request and the user does not need a Darwin account.

3. Execute

For a linked user, send the OAuth access token to the relevant Product API operation. For app-funded work, create and cast an application-scoped ephemeral goal with a stable pseudonymous reference and an idempotency key.

4. Receive events

Create a webhook subscription, store its one-time signing secret, verify signatures over raw bytes, and deduplicate every delivery ID. See webhooks.

5. Handle money states

Do not run work until Darwin confirms the required balance reservation. Handle funding_required and overage_approval_required as explicit user or application actions. See Connect pricing and Application Balance.