> ## 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.

# Authenticate

> Connect an external account when a thread requires it.

Authentication gives your Darwin account a scoped external connection. It does
not approve an action or authorize payment. Never put credentials in messages
or API arguments. This account-owned flow remains release-gated.

## Start from a request

When Get thread returns a pending authentication request, review its target,
authentication type, resource, scopes, and expiry. Then call Authenticate with
the exact `request`. The person chooses a supported method or a matching saved
credential in the hosted flow. Darwin checks saved credentials against the
target and scopes before reuse.

Darwin has fixed hosted flows for `oauth`, `bearer`, `api_key`, `password`, and
`username_password`. A provider may also use a namespaced method such as
`vendor.oauth_pkce`, but only when Darwin has an exact reviewed OAuth redirect
handler for that target, resource, scopes, and binding revision. An arbitrary
method name or redirect URL never creates an authentication flow.

```json theme={null}
{
  "request": "returned-request-id",
  "idempotencyKey": "connect-001"
}
```

The response contains `authentication`, `status`, and, when consent is needed,
a first-party `url` and `expiresAt`. Open only that URL. Its presence does not
prove the connection succeeded.

## Save a credential

If the hosted flow offers saved access, the account holder can choose it after
reviewing the target and scopes. The provider secret stays in the hosted flow;
the Account API returns only safe metadata and a Darwin `credentialId`. There
is no public standalone credential-setup endpoint yet, so connecting a service
ahead of a thread is not supported by this API.

## Check the outcome

Read the same thread for the verified connection or failure. Do not start a
second authentication attempt merely to check whether the first succeeded.

Status remains distinct across `awaiting_consent`, `authorizing`, `exchanging`,
`connected`, `expired`, `denied`, and `failed`. Only `connected`, backed by the
server's verified receipt, is success.

## Failure and safety

Do not retry an uncertain authorization-code exchange. Start a new attempt when
Darwin says the old one expired or failed. Account-list APIs expose only safe
metadata; tokens, passwords, provider state, and credentials never enter Act.
Provider adapters remain individually release-gated until live verification.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.