Authentication And Scoped Permissions
Curacel APIs use bearer authentication for approved customers and partners. Send the API credential in the Authorization header on every protected request.
Authorization: Bearer <CURACEL_API_KEY>
API credentials are issued during onboarding for a specific customer, partner, product, environment, and permission set. Treat each credential as a secret. Store credentials on trusted servers only, rotate them regularly, and revoke credentials that are no longer needed.
Current Authentication Method
Curacel currently documents bearer API key authentication for public API integrations. OAuth 2.0 or OpenID Connect support should only be used if Curacel has explicitly provisioned it for your integration.
Environments
Curacel separates sandbox and production access.
| Environment | Purpose | Credential handling |
|---|---|---|
| Sandbox | Development and integration testing | Use sandbox credentials only with sandbox endpoints and test data. |
| Production | Live customer, policy, claim, payment, or document workflows | Use production credentials only from trusted production systems. |
Scoped Permissions
Curacel credentials should be provisioned with the minimum permissions needed for the integration. Available permissions depend on the product and partner agreement.
| Permission | Description |
|---|---|
claims:read | Read claim records, claim status, and claim details. |
claims:write | Create or update claims and submit claim-related actions. |
policies:read | Read policy, product, quote, or coverage data. |
policies:write | Create quotes, bind policies, or update policy-related records. |
payments:read | Read payment, invoice, wallet, balance, or transaction records. |
payments:write | Create payment links, invoices, payouts, top-ups, or other payment actions. |
documents:read | Read document extraction jobs, results, and metadata. |
documents:write | Upload files and create document extraction jobs. |
webhooks:read | View configured webhook endpoints and delivery status. |
webhooks:write | Create, update, rotate, or remove webhook endpoints and secrets. |
admin:read | Read organization, user, provider, or partner configuration where allowed. |
admin:write | Manage organization, user, provider, or partner configuration where allowed. |
Product Permission Groups
| Product | Typical permission groups |
|---|---|
| Curacel Health | claims:read, claims:write, policies:read, admin:read, webhooks:read |
| Curacel Grow | policies:read, policies:write, payments:read, payments:write, claims:read, claims:write |
| Curacel Pay | payments:read, payments:write, webhooks:read, webhooks:write |
| Curacel Auto | policies:read, policies:write, claims:read, claims:write, documents:write |
| Curacel Extract | documents:read, documents:write |
Agent Integration Guidance
Agents should not ask users to paste Curacel credentials into chat. Agents should request credentials through the customer's approved secret manager, environment variables, or backend configuration.
Use the least privileged credential available. If a workflow only reads claim status, request claims:read, not claims:write or broad administrative access.
If a request fails with 401, the credential is missing, invalid, expired, revoked, or being used against the wrong environment. If a request fails with 403, the credential is valid but does not have the required permission for that operation.
Error Responses
{
"message": "Unauthenticated."
}
{
"message": "Forbidden.",
"required_permission": "claims:write"
}