External Integrations API v1

FlexiMetaDoc API Reference

This reference lists the partner API routes currently implemented by FlexiMetaDoc. The API host is the FlexiMetaDoc environment you use; copy the exact path and schemas from the generated contract.

Open interactive API documentation Download OpenAPI JSON

The generated OpenAPI document is the source of truth for request and response schemas. This API currently exposes tenant status, service identity creation, and ping. API credential issue, rotation, and revocation are performed in Organization Settings; they are not REST endpoints.

Available endpoints

Replace {tenantId} with the organization tenant ID and use the exact path shown below.

Method	Path	Required scope	Purpose
`GET`	`/api/v1/integrations/tenants/{tenantId}/status`	`integrations.read`	Return the authenticated client, tenant, granted scopes, and API version policy.
`POST`	`/api/v1/integrations/tenants/{tenantId}/identities`	`integrations.write`	Create a service identity using `serviceEmail` and `displayName`.
`POST`	`/api/v1/integrations/tenants/{tenantId}/ping`	`integrations.write`	Validate a signed write request and return the optional message. This endpoint requires an idempotency key.

The generated OpenAPI contract lists the current operation responses and validation schemas. Do not infer an endpoint from an example payload or field name.

Authentication and request signing

Partner calls use an active integration key ID and an HMAC-SHA256 signature. The server checks the tenant mapping, granted scope, timestamp, signature, and nonce replay state.

Header	Value	Rule
`X-Integration-Key`	Active key ID	Must identify an active, unexpired credential.
`X-Integration-Timestamp`	Unix epoch seconds	Must be within the configured clock-skew window (300 seconds by default).
`X-Integration-Nonce`	36-character hexadecimal-and-hyphen value	Must not have been used for this client credential before.
`X-Integration-Signature`	Uppercase hexadecimal HMAC-SHA256	Computed over the canonical request below using the credential secret.

canonicalRequest =
  UPPERCASE_HTTP_METHOD + "\n" +
  REQUEST_PATH + "\n" +
  RAW_QUERY_STRING + "\n" +
  X-Integration-Timestamp + "\n" +
  X-Integration-Nonce + "\n" +
  UPPERCASE_HEX(SHA256(raw_request_body_bytes))

X-Integration-Signature = UPPERCASE_HEX(HMAC_SHA256(key_secret, UTF8(canonicalRequest)))

Sign the exact path and raw query string sent on the request. Hash the exact body bytes; use an empty body for GET requests. Hexadecimal signatures must be uppercase.

Idempotency and request limits

POST /ping requires exactly one Idempotency-Key header containing 1–128 non-blank characters. Reusing a completed key replays its result; a concurrent duplicate receives a conflict response.
The other documented routes do not currently require an idempotency header.
Partner API traffic is limited to 120 requests per minute per client and tenant.
Responses include a correlation ID. Use it when contacting support about a failed request.

Manage integration credentials

Organization administrators with integration management access can register service clients and issue, rotate, or revoke credentials in Organization Settings → Inbound identities.

Credential management currently uses the authenticated FlexiMetaDoc web interface. The public partner API does not expose service registration, API key issuance, rotation, or revocation routes.

Errors and versioning

Read the operation-specific status codes and error schemas in the generated OpenAPI contract. Errors include a correlation ID; validation and authorization errors may have different response shapes across operations.

Version 1 remains backward compatible within its major version. Any deprecation notice and replacement version are returned by the status and ping operations.