Skip to main content

Authentication

Every request under /api/v1/* requires a bearer token. GET /health is the only unauthenticated route — use it for connectivity checks.

Provisioning​

Your API token is provisioned out-of-band by the Rosetta team as part of setting up your integration. There is no self-service token creation endpoint. Treat it as a secret: send it only over HTTPS, never log it, and never embed it in client-side code. If you suspect it has been exposed, contact your Rosetta integration contact to have it rotated.

Sending the token​

Send the token in the Authorization header on every /api/v1/* request:

Authorization: Bearer <SYNC_ENGINE_API_TOKEN>

For example:

curl https://sync.example.com/api/v1/changes \
  -H "Authorization: Bearer <SYNC_ENGINE_API_TOKEN>"

Failure behavior​

A missing Authorization header, a header that isn't exactly Bearer <token>, and an incorrect token are all indistinguishable from the outside: each returns

401 Unauthorized
{ "code": "unauthorized" }

There is no 403 response from this API — a request is either authenticated with a valid token or it is rejected with 401. A valid token grants access to every route documented on this site.

Worked example​

  1. Provision — your Rosetta contact issues a token; store it as an environment variable, never in code: 
    export ROSETTA_SYNC_TOKEN="<token from your operator>"
  2. Send the header — include it on every /api/v1/* request: 
    curl https://sync.example.com/api/v1/changes?since=0 \
      -H "Authorization: Bearer $ROSETTA_SYNC_TOKEN"
    A valid token returns 200 with the requested body (see Change Feed).
  3. Observe the failure shape on a bad token — an incorrect or missing token returns the same 401 regardless of which was wrong: 
    curl https://sync.example.com/api/v1/changes?since=0 \
      -H "Authorization: Bearer not-a-real-token"
    { "code": "unauthorized" }