Duvo Auth And Access
Duvo access is workspace-scoped. Agents, API clients, MCP servers, and webhooks inherit the policies, approvals, and permissions configured for the customer workspace.
Discover
- Protected resource metadata: https://api.duvo.ai/.well-known/oauth-protected-resource.
- OAuth authorization server: read it from
authorization_serversin the protected resource metadata, then fetch that server's OpenID Connect discovery document. - Agent-readable auth guide: https://www.duvo.ai/auth.md.
- OpenAPI security schemes: https://www.duvo.ai/openapi.json under components.securitySchemes. There is one,
bearerAuth, an HTTP bearer scheme for API keys and OAuth access tokens.
Pick A Method
- Use bearer API keys for workspace API access, available in any Duvo workspace, including Free. A person creates them in the app at https://app.duvo.ai/settings/profile#api-keys.
- Use OAuth 2.0 sign-in (authorization code with PKCE) when a person can sign in through a browser. MCP hosts and
duvo loginwork this way. Request the scopesopenid profile email offline_access. There is no machine-to-machine OAuth grant, so unattended clients use an API key. - Use SSO and RBAC for human users in the Duvo application.
- Use managed OAuth/API connections for third-party business systems such as ERP, CRM, email, spreadsheets, supplier portals, and collaboration tools.
- MCP hosts can register themselves as OAuth clients with Dynamic Client Registration, discovered from https://api.duvo.ai/.well-known/oauth-protected-resource/v2/mcp.
Register
Registration is self-serve. People sign up at https://app.duvo.ai, and Duvo creates a Free plan workspace at first sign-in. MCP hosts register themselves as OAuth clients through Dynamic Client Registration (RFC 7591), with no request to Duvo. API keys are created by a person in the app, not through the API.
Enterprise tenants, SSO, and pilots are scoped with the Duvo team at https://www.duvo.ai/contact.
Claim
After sign-up, a person creates an API key at https://app.duvo.ai/settings/profile#api-keys (shown once), or an agent signs in with OAuth through an MCP host or duvo login. Credentials should be stored in a secret manager and never embedded in prompts, logs, client-side code, or public repositories.
Use Credential
- Send the API key or OAuth access token as
Authorization: Bearer <token>. - A credential acts as its user, with that user's role in each team. A team-scoped API key acts only in its team. A key for all teams, or an OAuth token, acts in any team the user belongs to; name the team in the path of team endpoints (
/v2/teams/{team_id}/...), and list the teams withGET /v2/teams. Keys for all teams work only on /v2. - Retried writes are not deduplicated. Read the current state before you retry one (see /api-reference.md).
- Treat 401 as missing, expired, malformed, or revoked credentials.
- Treat 403 as a role, team membership or plan restriction. It does not mean a scope is missing, so a token with other scopes does not help.
Errors
Errors are JSON with a human-readable error string. Some also carry a message with more detail, and a few carry other fields. Duvo has no stable machine-readable error code yet, so branch on the HTTP status:
- 400: the request is invalid. Fix it before sending it again.
- 401: the credential is missing, expired, revoked or not recognised. Sign in again or use a valid API key.
- 403: the user's role, team membership or plan does not allow the action. Retrying does not help.
- 404: the resource does not exist, or it belongs to a team the credential cannot act on.
- 409: the resource is in a state that does not allow the change, for example answering a human request while the run is still executing.
- 429: rate limited. Wait the number of seconds in
Retry-After, then retry. - 5xx: a Duvo error. Read the current state before you retry a write.
Revocation
Revoke an API key by deleting it in the app. Its creator can delete it, and a team manager can delete the team's keys. A key can also be created with an expiry. MCP hosts that signed in with OAuth handle token refresh and revocation themselves. Agents must stop using revoked credentials immediately, clear cached tokens, and get a new credential before resuming privileged work.
Supported Auth Models
- Bearer API keys for workspace API access, created in the app in any Duvo workspace, including Free.
- OAuth 2.0 sign-in with PKCE for MCP hosts and
duvo login, using the scopesopenid profile email offline_access. - SSO and RBAC for human users in the Duvo application.
- Managed OAuth/API connections for third-party business systems such as ERP, CRM, email, spreadsheets, supplier portals, and collaboration tools.
Agent Constraints
- Agents cannot see raw third-party passwords when credentials are stored in managed connections.
- Agents cannot bypass human approval gates, workspace RBAC, SSO, audit logging, or customer policy.
- Sensitive write actions should be scoped and routed through human-in-the-loop approval where required.
- Duvo has no per-endpoint scopes, so limit what an agent can reach with a team-scoped API key created by a user whose role fits the workflow.
Scopes
OAuth requests only the OpenID Connect scopes openid, profile, email, offline_access. Duvo does not issue per-endpoint API scopes yet, and read and write access are not separated by scope. What a key or token can do follows its user's role in each team, and an API key can be limited to one team.
Machine-readable source:
https://www.duvo.ai/auth.md