Quick Start

New here? Start by exploring a complete reference MassID in Carrot Explorer — then come back to walk through how to build one.

This guide walks through the base Carrot API flow — from authentication to document retrieval — so you can verify your integration end to end.

Integrator learning path

1) Request an access token

Use OAuth 2.0 client credentials:

curl --request POST \
  --url https://auth.api.carrot.eco/oauth2/token \
  --header 'Authorization: Basic <base64(clientId:clientSecret)>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=api.carrot.eco/main-scope'

Endpoint details: Authentication.

2) Create a document

Create the base traceability record:

POST /documents
Authorization: Bearer <access_token>

Endpoint details: Documents.

3) Append an event

Add one timeline event to represent a business action:

POST /documents/{documentId}/events
Authorization: Bearer <access_token>

Endpoint details: Events.

For batch operations, use POST /documents/events to submit multiple events in a single request. See Events — Batch events.

4) Retrieve and validate state

Fetch the full document and verify timeline consistency:

GET /documents/{id}
Authorization: Bearer <access_token>

Endpoint details: Documents.

5) Add production safeguards

• Use deduplicationId on retryable create/event requests.
• Enforce event timestamp ordering.
• Add client-side rate limiting and retry/backoff.

Continue with:

• Core Concepts — the document model and event-sourced architecture.
• Environments — test vs. production credentials and go-live checklist.
• Submitting a MassID — complete lifecycle walkthrough.