DutyClaims Docs
Authentication

Managed credentials first, sandbox OAuth where explicitly supported.

Production integrations should assume managed credentials issued through DutyClaims partner onboarding. Sandbox OAuth client credentials exist to support partner testing, not to hide the production credential model.

Production

Managed credentials

Most routes accept the managed credential in the Authorization header. Some integrations can also send X-API-Key directly where documented.

curl https://api.dutyclaims.com/v1/clients \
  -H "Authorization: Bearer dcp_live_replace_me"

curl https://api.dutyclaims.com/v1/claims/status?claimId=clm_123 \
  -H "X-API-Key: dcp_live_replace_me"
Sandbox Only

Sandbox OAuth client credentials

The sandbox token endpoint issues opaque bearer tokens for approved sandbox partner clients only. Production access is still managed-credential centric.

curl -X POST https://api.dutyclaims.com/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=dc_client_id&client_secret=dc_client_secret"

The current auth semantics are also present in the live contract at https://api.dutyclaims.com/v1/docs/openapi.

Supported security schemes

SchemeTypeCurrent meaning
BearerApiKeyhttp (bearer)Managed broker API key issued through the DutyClaims broker or admin UI.
XApiKeyapiKey • header X-API-KeyNo description published.
OAuthBearerhttp (bearer)OAuth client-credentials bearer token for sandbox partner integrations.

Current credential decision matrix

SurfaceProduction defaultSandbox optionDo not assumeExamples
Partner workflow routes
71 operations across 9 families		Authorization: Bearer dcp_live_... using the managed credential.Use the same bearer header shape with a sandbox managed credential or an approved sandbox OAuth token.Do not assume X-API-Key is interchangeable on these families.
Diligence compatibility routes
5 operations		Authorization: Bearer dcp_live_... remains valid.The published compatibility surface also allows X-API-Key.Do not assume sandbox OAuth is the current contract path for diligence routes.
Public and token-issuance routes
6 operations		No partner credential required.No partner credential required.Do not send managed partner secrets to public reference or invite-accept routes just because your client library can.

Current scope vocabulary

ScopeMeaning
partner.readRead access to the corresponding partner surface.
partner.manageCapability-gated workflow permission enforced by the API.
clients.readRead access to the corresponding partner surface.
clients.writeWrite access to the corresponding partner surface.
authority.readRead access to the corresponding partner surface.
authority.writeWrite access to the corresponding partner surface.
revenue.readRead access to the corresponding partner surface.
webhooks.readRead access to the corresponding partner surface.
webhooks.writeWrite access to the corresponding partner surface.
diligence.readRead access to the corresponding partner surface.
diligence.submitWrite access to the corresponding partner surface.
financing.requestCapability-gated workflow permission enforced by the API.
litigation.enrollCapability-gated workflow permission enforced by the API.
notifications.readRead access to the corresponding partner surface.
notifications.writeWrite access to the corresponding partner surface.

How to choose the credential

  • Default to managed credentials for production traffic unless DutyClaims explicitly enabled a different flow for your tenant.
  • Use Authorization: Bearer … as the safest default for every family except the public routes and the diligence compatibility path that also advertises X-API-Key.
  • Use X-API-Key only where the live route contract still publishes it, not as a blanket fallback header.
  • Use sandbox OAuth only when your testing plan explicitly depends on client-credentials issuance and the tenant is approved for it.

Common auth failure paths

  • 401 Unauthorized usually means the credential is malformed, revoked, or attached to the wrong header.
  • 403 Forbidden usually means the partner lacks capability, scope, or environment readiness for the route.
  • 429 Too Many Requests is operational, not authz, and should be handled through retry discipline.

Operational rules

  • Do not treat sandbox OAuth availability as proof that the same flow is enabled for production tenants.
  • Read the route family before choosing the credential; the current contract is not uniform across diligence, public, and partner workflow surfaces.
  • Rotate managed credentials when partner ownership or environment state changes.
  • Honor 401, 403, and 429 problem responses instead of retrying blindly.
  • Keep partner capability state aligned with the scopes you request and the routes you call.