Reviewing Organization Links
The Global.Church platform distinguishes between two pathways:
- Organization links go through human review before an organization can act through the API.
- Engagement attestations, needs, and commitments are submitted by an organization's stewards and propagate directly to the knowledge graph — there is no admin approval step.
This guide covers both pathways.
Organizations and the Home
An organization is created and held in the Home, the sign-in service engage and platform use. Who belongs to it, and who stewards it, is decided there: a steward is a person the organization has delegated to act for it. Global.Church does not keep its own list of members.
What Global.Church keeps is a link between a Home organization and its record in the directory. A steward asks for the link; a reviewer confirms it. Once confirmed, the organization's stewards can submit on its behalf, and the API checks their stewardship against the Home on every write.
Lifecycle
-
Requested -- A steward creates or selects their organization in the Home, then names the directory record it is (or describes an organization that is not listed yet). The request is created as
pending; nothing takes effect until it is confirmed. -
Domain check -- When the organization's web domain is known, the API looks for
https://<domain>/.well-known/gc-org.jsonnaming the organization's Home id, and stores the result with the request. A match is strong evidence; a missing file never blocks confirmation. -
Reviewed -- A Global.Church reviewer confirms or rejects the request, or re-runs the domain check. For an organization not yet in the directory, confirming also creates its directory record; the reviewer may set or correct the record at confirmation.
-
Confirmed -- The link is effective. The organization's stewards, as the Home reports them, can submit for it.
-
Rejected -- The request is marked
revoked, with the reviewer's note kept in its evidence.
Where to review
Links are reviewed in the platform admin dashboard at platform.global.church/admin/claims.
The admin or support platform role is required, with the claims:review permission.
What to check
When confirming a link, verify:
- The right record -- Is the directory record the one the organization says it is? Compare the name and website in the request with the record.
- Domain evidence -- Did the domain check match? Treat a mismatch as a question to resolve before confirming, and a missing file as no evidence either way.
- Organization legitimacy -- Does the organization look complete and real? Check the name, website, and type.
- Existing links -- Each Home organization and each directory record can hold one confirmed link. A second request for either is refused by the API.
Who can act for a linked organization
| Role | Where it comes from | What they can do |
|---|---|---|
| org_admin | A steward of the organization in the Home, with a stewardship delegation that is in force | Submit engagement attestations, declare needs and commitments, change their status, publish or unpublish the link |
| org_member | A member of the organization in the Home | View organization data |
Roles are read from the Home at request time, never stored by Global.Church. Someone who stops being a steward loses the ability to submit as soon as the Home says so.
Engagement attestations, needs, and commitments
These are submitted via the API by an organization's stewards. There is no admin review step — the API verifies the caller is a steward of the referenced orgUri in the Home, then writes the record directly. A database trigger propagates the new or updated record to the knowledge graph in seconds.
What gets verified at submission
| Check | Where |
|---|---|
Caller's Home sign-in token is valid (x-home-id-token) | API gateway |
Caller is a steward of orgUri in the Home, and the record has a confirmed link | API |
Engagement accelerator codes are Phases of Engagement Toolkit domain codes (PRA … MKT, the twelve top concepts of poe:EngagementAcceleratorScheme) | API |
For commitments: concernsNeedId references a real need (if supplied) | API |
For attestations: fulfillsCommitmentId references a real commitment (if supplied) | API |
| Field shapes match SHACL constraints (people group references resolve, org URIs are well-formed) | GraphDB load |
If the Home cannot be reached, the write is refused with 503 rather than accepted on stale information.
Where the data lands
| Submission | Named graph |
|---|---|
Engagement attestation (POST /v0/engagement-claims/submit) | <https://data.global.church/engagement-claims/> |
Need (POST /v0/needs) | <https://data.global.church/needs/> |
Commitment (POST /v0/commitments) | <https://data.global.church/commitments/> |
See Needs & Commitments for the full submission flow.
Platform roles required for link review
| Action | Required role | Required permission |
|---|---|---|
| Review organization links | admin or support | claims:review |
| Manage user roles | admin | roles:assign |
| View all users | admin or support | users:read |
Next steps
- Knowledge Graph Overview -- understand what data is in the graph
- Data Quality and SHACL -- how data is validated
- Adding a Country -- add a new country to the dashboard map