Skip to main content
Every public product API call requires authentication, including Search, Get search request, Act, Assist, and Publish. Use a Darwin API key in x-api-key, or an approved OAuth access token in Authorization: Bearer. Never put server API keys in a browser, mobile app, or agent conversation.

​
1. Create your application and key

Create and verify your account, then register an application with POST /api/v2/account/applications. Your signed-in account session authorizes registration; you do not need an API key before creating your first one. Create an API key with POST /api/v2/account/api-keys using the same signed-in session. Choose the narrowest scopes. Darwin shows the secret once; store it on your server. An application key with directory:read can Search under your application’s identity. It does not identify an end user and cannot authorize private reads, Act, authentication, or payment on a customer’s behalf.
Use the same owner credential for follow-ups and GET /api/v3/search/{searchId}. A Search ID or guest Search token alone is not API authentication. Missing, invalid, expired, or revoked credentials return 401; insufficient scope or ownership returns 403.

​
2. Choose who authorizes and pays

​
Connect your users

Send each person through Darwin sign-in and OAuth consent. Your application receives a scoped access token. Users keep their API keys private and bring their own identity, plan, credits, and approvals. Connecting them is free for your application; Search remains ad-supported under the connected-user experience. For Act on a person’s behalf, obtain their account-level human:actions grant. A target must also be executable, and provider access, actions, and payments can require separate approval. Consent never guarantees provider completion.

​
Run work for your own account

Use your own account key with the required scopes for work you own. For Act, use a user key with directory:read, agent:read, and agent:write; the API verifies the selected agent or account authority again. An application Search key cannot perform that work. Your account pays the listed API usage rates. Developer-paid Search requests return results without ads. Do not reuse your own account key or OAuth grant to impersonate customers: it has your authority and spending context. Assist and Publish use API-key authentication with their documented scopes. Keep credentials and any request-specific access tokens private. API Reference describes each operation’s accepted credential.

​
3. Preserve ownership and safe retries

  • Search and Get search request use the same authenticated owner.
  • Act starts or continues one authorized thread. Preserve actRequestId, threadId, and exact pending request IDs.
  • Assist plans, executes, and updates one assistId; planning does not start paid work.
  • Reuse Idempotency-Key with identical inputs when retrying a write after an ambiguous response.
  • On 429, wait for Retry-After, then use bounded backoff with jitter.
Rate limits are shared across credentials owned by the same account. Key rotation, OAuth clients, applications, and acting agents do not create new allowances. A workspace subscription does not automatically raise API request limits.

​
MCP and website access

MCP requires Darwin sign-in and scoped consent before connecting, including Search. OAuth discovery, login, verification, and initial credential setup are bootstrap flows. The website can provide guest browsing through its separate scoped guest session; that session is not a credential for the public developer API.
Last modified on October 27, 2026