Organization Metadata — Proposed Guide

Organization Metadata: Metadata provides small integration-owned annotations without changing core organization semantics. It should not become a…

Overview

Metadata provides small integration-owned annotations without changing core organization semantics. It should not become a container for secrets or unrestricted personal information.

Key concepts

Use namespaced keys and define whether a patch merges, replaces or removes entries. Bound the size and allowed value types.

Implementation considerations

Prevent a metadata value from overriding authorization, accounting identity or payment state. Treat externally supplied annotations as untrusted data.

Proposed API behavior

PATCH /v1/organizations/{organization_id}/metadata is an illustrative design for this topic. Path and field names may change before implementation. Access would require an authorized organization context and operation-specific permission; no public API or authorization grant is available here.

Static example requests

# Proposed request text only; this reserved host is not a live API.
curl -X PATCH 'https://api.remizen.example/v1/organizations/org_example_123/metadata' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
  "metadata": {
    "example.source": "local-fixture"
  },
  "version": 1
}'

Fictional response example

{
  "data": {
    "organization_id": "org_example_123",
    "metadata": {
      "example.source": "local-fixture"
    },
    "version": 1,
    "id": "organizations_example_123"
  },
  "meta": {
    "request_id": "req_example_123",
    "reference_only": true
  }
}

Illustrative error case

Review this failure case in context: Prevent a metadata value from overriding authorization, accounting identity or payment state. Treat externally supplied annotations as untrusted data.

{
  "error": {
    "code": "validation_error",
    "message": "The proposed organization metadata operation requires review of its input or authorization.",
    "request_id": "req_example_123"
  }
}

Proposed data types

Related documentation