Skip to main content
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.
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.
Last modified on October 5, 2026