HAPI FAQ: Identity Management API for Users, Roles, Organizations, and Committees

HAPI FAQ – Identity Management API (users, roles, organizations, committees)

Where is the Identity Management API documented?

XSD: https://bitbucket.org/sdo-hapi/data-models/src/master/schema/xsd/identities%2Broles/harmonized-identities-roles.xsd
OpenAPI YAML:
- https://bitbucket.org/sdo-hapi/api-specifications/src/master/openapi-v3/iec-identities-roles-openapi3.yaml
OpenAPI: IEC API Portal – https://api-portal.iec.ch/ (developer account required)

What do the main endpoints return?

Endpoint	Returns
`GET /persons`, `/organizations`, `/committees`, `/roles`	First 100 entries (use pagination)
`GET /{entity}/{urn}`	One record
`GET /{entity}/{urn}/roles`	All roles of the entity

Common use cases

Need	Call
All committees	`/harmonized/committees`
URN of a committee	`/harmonized/committees?reference=TC 100/MT 62394`
Members of a committee	`/harmonized/committees/{urn}/roles?key=MEMBER` (repeat per key, e.g. `PROJECT_LEADER`)
NC memberships of a TC	`/harmonized/committees/{urn}/roles?key=MEMBER_OBSERVER` and `?key=MEMBER_PARTICIPANT`
URN of a user	`/harmonized/persons?userName={username}`
Roles of a user	`/harmonized/persons/{urn}/roles`
URNs of all experts of an NC	`/harmonized/roles?toUrn={NC org urn}&key=DEPENDENCY`
Data of all experts of an NC	`/harmonized/persons?ownerUrn={NC org urn}`
All mirror committees of an NC	`/harmonized/committees?ownerUrn={NC org urn}`
All CENELEC committees	`/harmonized/committees?ownerUrn=iec:org:3353`

Why must I call `/roles` twice?

Roles are directional (from → to). To get all relations of an entity, query both fromUrn and toUrn.

What are the main role keys between committees?

Key	Meaning
`MEMBEROF`	A is member of B
`MEMBER_PARTICIPANT` / `MEMBER_OBSERVER`	P-member / O-member
`SECRETARIAT`	A holds the secretariat of B
`PARENT` / `CO_PARENT`	A is (co-)parent of B (co-parent: JWG/JMT/JPT)
`LIAISON_IEC`, `LIAISON_ISO`, `LIAISON_A/B/C`	Liaisons
`AFFILIATE_SELECTED_COMMITTEE`	B is a TC/SC selected by affiliate A
`NC_STANDARDIZATION_ORGANISATION`	A is the NC standardization organization of B
`REGIONAL_PARTNER`, `COOPERATIONAGREEMENT_MOU`	Regional / international partner

Person-to-committee keys include CHAIR, SECRETARY, CONVENOR, PROJECT_LEADER, EXPERT, MEMBER, OBSERVER, DEPENDENCY, plus NC-specific keys prefixed by the NC (e.g. UTE_, NEN_, SAC_, JISC_). Full list: see the technical documentation.

What are committee types?

type in /committees, e.g. TECHNICAL_COMMITTEE, SUBCOMMITTEE, WORKING_GROUP, PROJECT_TEAM, MAINTENANCE_TEAM, JOINT_WORKING_GROUP, SYSTEM_COMMITTEE, CENELEC types (CLC_*), NC mirror types (e.g. CEI_*, NEK_*), and NC member categories (NC_FULLMEMBER, NC_ASSOCIATEMEMBER, NC_AFFILIATE_COUNTRY).

What status values exist?

Committees / organizations: ACTIVE, DISBANDED
Persons: ACTIVE, INACTIVE

⚠️ Status values are not harmonized with ISO.

What data can my application see?

Access depends on data ownership:

Entity	Owner
Person	NC of the main dependency (IEC for international organizations)
Committee	IEC for IEC TC/SC, CENELEC for CENELEC TCs, the NC for mirror committees
Organization	IEC for NCs and international/regional/global companies; the NC for country companies
Role	Two owners: owner of `from` and owner of `to`

Rules:

IEC has access to everything.
An owner has full access to its own data.
IEC-owned data (committees, roles in IEC committees) is visible to everyone.
CENELEC members see CENELEC-owned data; CENELEC sees its members' data.
ISO sees IEC-owned data only.
NC mirror committees of another NC are hidden.
Default: unauthorized.

Which person fields are public or restricted?

Public: URN, status, names, salutation, title, initials, type, preferred language, owner, sortKey, timestamps.
Restricted (owner only): notification email, postal address, phone, userName, personal email.

Seeing a role does not grant access to the restricted data of the person in it.