Data Governance - API Access & Endpoint Controls

How administrators determine what data can be sent to which destination, which endpoints any given key can call, and the full audit trail of every external request.

Elker's external API is deny‑by‑default at every layer: keys, endpoints, schema fields, and associations. Turning a capability on is an explicit administrative action; removing it is a single configuration change. Every call that passes the gates is logged with full request metadata so there is always an answer to "what left the platform, to where, and on whose authority".

1. The four layers of control

A request to the external API must pass all four of the following gates before Elker returns any data. Each gate is independently configurable from the admin UI and can be tightened or revoked without code changes or vendor involvement.

1. Authentication The request must present a valid API key. Keys are 64‑hex‑character tokens, scoped to a single organisation tenant, and rotatable at any time.

2. Key permissions Each key holds an explicit permission set (read, write, or both). GET/HEAD requests demand read; all other methods demand write.

3. Endpoint allow‑list The organisation's external‑API configuration must explicitly enable the matched endpoint. Any endpoint not in the allow‑list returns 403 Endpoint not enabled.

4. Field & association filter Only fields and associations listed in the organisation's schema configuration are serialised into the response. Everything else is stripped before the payload leaves the server.

All four gates are evaluated per request. Revoking a key, removing an endpoint, or un‑enabling a field all take effect on the next request - there is no cache to flush or deployment to run.

Layer	Configured by	Stored as
API keys	Admin / Owner	`external_api_keys`
Key permissions	Admin / Owner	Per‑key JSON array
Endpoint allow‑list	Admin / Owner	`external_api_config.endpoints`
Field / association filter	Admin / Owner	`external_api_config.schemas`
Access log	Written automatically	`external_api_access_logs`

2. Endpoint‑level allow‑listing

The most common data‑governance question - "which keys can call which endpoints?" - is answered by the endpoint allow‑list. Each organisation maintains a configuration mapping specific METHOD PATH pairs to an enabled: true/false flag. Paths support parameter placeholders (e.g. {id}) and are matched exactly - there is no wildcard that opens whole route trees.

GET

/api/external/reports

List reports (paginated)

GET

/api/external/reports/{id}

Retrieve a single report

POST

/api/external/reports

Create a new report

PATCH

/api/external/reports/{id}

Update report status / metadata

GET

/api/external/statuses

List allowable statuses

DELETE

/api/external/reports/{id}

Delete a report (right‑to‑erasure)

No implicit enablement. An endpoint is either explicitly enabled or it returns 403. Adding a new external‑API endpoint to the platform does not automatically expose it to existing integrations.

// external_api_config
{
  "endpoints": {
    "GET /api/external/reports":       { "enabled": true  },
    "GET /api/external/reports/{id}":  { "enabled": true  },
    "POST /api/external/reports":      { "enabled": false },
    "PATCH /api/external/reports/{id}":{ "enabled": true  },
    "DELETE /api/external/reports/{id}":{ "enabled": false }
  },
  "schemas": {
    "Report": {
      "fields": [
        "id", "codename", "status",
        "report_type", "created_at", "tags"
      ],
      "associations": {
        "custom_fields": { "enabled": true  },
        "contacts":      { "enabled": false },
        "activities":    { "enabled": false }
      }
    }
  }
}

Bound to the Swagger schema. The config is intersected with Elker's OpenAPI definition at read time. Renaming or removing an endpoint in the platform automatically drops it from the effective config - stale entries cannot be used to re‑expose removed routes.

3. Per‑key permissions & rotation

elk_k8x2…f9m1 READ

elk_p4n7…a2v6 READ WRITE

elk_3bc9…e7d2 READ

A GET or HEAD request requires the key to include read; any other method requires write. A key without the required permission returns 403 Not authorized before the endpoint allow‑list is even consulted.

Least‑privilege by default. Issue separate read and write keys for separate pipelines. A BI tool that only needs to pull data should hold a read‑only key; a case‑management sync that updates status needs its own read+write key.

Create named key

Secure random 64‑hex‑character token generated server‑side; shown to the admin once

Scope to profile (optional)

Bind the key to a non‑group profile so every call is attributable to a specific service identity

Revoke instantly

Delete the key to cut off all access immediately - no grace period

Track last‑used

Every successful authentication updates last_used_at, so dormant keys are easy to identify and retire

4. Access logging & audit trail

Every request that reaches the external API - whether it succeeds or is rejected - writes a row to the access log. The log captures enough metadata to reconstruct exactly what left the platform, from where, and under which key. It is tenant‑scoped and indexed by (organization_id, created_at DESC) for fast timeline queries.

16:42:08Z GET /api/external/reports?page=2 200

16:42:09Z GET /api/external/reports/RPT‑0291 200

16:42:11Z POST /api/external/reports 403

16:43:02Z GET /api/external/statuses 200

16:44:31Z DELETE /api/external/reports/RPT‑0288 403

Field	Purpose
endpoint	Request path - matched against the allow‑list config
method	HTTP verb - determines read vs write permission
ip	Remote IP address of the caller
user_agent	Identifies the integration client
status	HTTP response status (including 401/403 denials)
params	Query parameters (filters, pagination)
body	Request body, truncated to 10 KB for POST/PATCH
external_api_key_id	Foreign key - joins to the key used (named, profile‑scoped)

Compliance‑ready audit trail. Because logs capture key id, IP, method, path, status, and truncated body, incident investigations ("who pulled this report, when, from where?") resolve to a single query.

5. Data governance in practice

Suppose your organisation wants a BI warehouse to pull report headers only - no case notes, no reporter details, no activities. The administrator takes four steps:

Create a named API key warehouse‑sync with read‑only permissions.
Enable only the two list endpoints (GET /reports, GET /reports/{id}) in the endpoint allow‑list.
In the Report schema config, enable only the header fields (id, codename, status, report_type, created_at, tags) and leave custom_fields, contacts, activities disabled.
Issue the key to the warehouse pipeline.

Any attempt by the warehouse to call POST /reports, to retrieve contacts, or to request case notes returns 403 or a filtered response - and leaves a log entry explaining which gate blocked it.

This article covers the external API governance surface - determining what data can be sent to what location via integration. Elker applies the same deny‑by‑default posture to other surfaces, each documented separately:

Webhooks	Outbound event notifications - named destinations, active/inactive toggle, custom headers, retry policy.
Consent & retention	Reporter consent choices filter API responses; deletion events propagate to subscribers.
Tenant isolation	Every external‑API request is already scoped to the key's organisation tenant; cross‑tenant reads are structurally impossible.
AI data sharing	The separate AI features article covers what can be sent to AI providers under which controls.

One principle, four surfaces. Keys, endpoints, fields, and destinations are all opt‑in, admin‑configurable, and logged. Revoking access in any of them is a single administrative action.