Partner Write API

This guide covers machine-to-machine writes from partner systems (for example, cesam-la.pt) into Legaciti.

Base URL

• https://api.legaciti.org

Authentication Model

Partner writes use scoped API keys in the X-API-Key header.

• Keys are provisioned by Legaciti operators in dashboard site-tools.
• Keys are stored hashed server-side.
• Each key has explicit scopes.
• Rate limiting is applied per key.

Supported Scopes

• ingest: allows POST /api/ingest
• membership.update: allows POST /api/partners/people/:orcid/membership

If a key is valid but does not include the required scope, the API returns 403.

Endpoint: Queue Ingestion

POST /api/ingest

Required scope: ingest

curl -X POST https://api.legaciti.org/api/ingest \
  -H "X-API-Key: $PARTNER_INGEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"orcid_ids": ["0000-0002-8685-5194"]}'

Successful response:

{
  "queued": 1,
  "requested": 1
}

Endpoint: Update CESAM Affiliation

POST /api/partners/people/:orcid/membership

Required scope: membership.update

curl -X POST "https://api.legaciti.org/api/partners/people/0000-0002-8685-5194/membership" \
  -H "X-API-Key: $PARTNER_MEMBERSHIP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "cesam",
    "status": "cesam"
  }'

Request body:

• entity_id: must be cesam
• status: cesam or external
• starts_at: optional unix timestamp in milliseconds

Successful response:

{
  "success": true,
  "affiliation": {
    "person_orcid": "0000-0002-8685-5194",
    "entity_id": "cesam",
    "status": "cesam",
    "starts_at": 1742900000000,
    "ends_at": null
  }
}

Error Handling

• 401: missing, invalid, or inactive API key
• 403: key does not have required scope
• 400: invalid request body
• 404: researcher or entity not found
• 429: key exceeded configured per-minute request limit