Configuration

Base URL

All endpoints are rooted under a single, tenant-shared base URL:

{{BASE_URL}}/api/v1/...

Your base URL is provided by Conforma at onboarding. Typical environments:

Use the sandbox base URL in all examples of this documentation during your integration; swap it for the production URL only when you are ready to go live.

Authentication

ConformaESG supports two customer-facing authentication channels.

Web session cookies

POST /api/v1/auth/login authenticates a user and sets the ces_session cookie. Browser clients must also call GET /api/v1/auth/csrf and send the returned CSRF token as X-CSRF-Token on POST, PUT, PATCH and DELETE requests made with the session cookie.

curl -X POST {{BASE_URL}}/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "user@example.com", "password": "********" }'

Personal access tokens

PATs are created through /api/v1/auth/api-keys. The API returns the token only once at creation time. Store it in your secret manager and send it on each request:

curl {{BASE_URL}}/api/v1/auth/me \
  -H "Authorization: Bearer $CONFORMA_PAT"

PAT scopes follow the module:access pattern, for example suppliers:read or purchases:write. Use GET /api/v1/auth/api-keys/scopes to list scopes the current user can grant.

Tenant scoping

The ConformaESG API is multi-tenant. Every request you make is automatically scoped to the tenant your credentials belong to:

• GET requests only return records belonging to your tenant.
• POST requests create records under your tenant.
• Records from other tenants are never visible.

You do not need to pass a tenant identifier in any query parameter or body field. Tenant context is derived server-side from the session or PAT.

X-Tenant-Id is not part of the normal customer-facing integration contract. Use it only if Conforma explicitly enables it for a development or onboarding scenario.

Required HTTP headers

Do not set Content-Type manually when using browser FormData; let the HTTP client include the multipart boundary.

Entitlements

Each tenant has a subscription that activates a subset of domain modules (for example: suppliers, textile, traceability, chemicals). Endpoints belonging to a module that is not active for your tenant will return 403 Forbidden.

Use GET /api/v1/auth/me at startup to inspect the authenticated user and tenant context. The legacy /api/v1/me endpoints remain documented only for older integrations.

Upload modes

Small files can be uploaded directly with multipart/form-data on the resource-specific upload endpoint. Large files should use the presigned flow:

1. Call a presign endpoint with file metadata.
2. Upload the file bytes directly to the returned presignedUrl.
3. Call the matching complete endpoint with checksumSha256.

See Documents, Purchase Documents and Product Materials for the exact request shapes.

Rate limits & quotas

Fair-use rate limits apply. If you exceed them, the API responds with 429 Too Many Requests. Implement exponential backoff on retryable statuses (429, 502, 503, 504).