Affiliations API

The affiliation API corresponds to the affiliations resource of the SCIM API.

→ Affiliations API documentation.

The main use case for the affiliation API is to implement the push method for affiliation synchronization. It allows an organization to create, modify and delete the current affiliation of a user’s edu-ID identity.

Former affiliations are implicitly created when a current affiliation of an individual is deleted. Currently, no API is specified to manage former affiliations.

The affiliation resource has been designed to match as closely as possible the AAI attribute specification. All AAI attributes are represented in this SCIM-extension defined by SWITCH.

Basic concepts

IdM Process

API Method

A new member (e.g. a student) has been accepted at the organization

POST request. For a given edu-ID identifier set the user’s organizational attributes.

An attribute of an existing member changes (e.g. name change, or role change)

PUT request (overwrite all organizational attributes of a member identified by the organizational unique identifier)

A member is leaving the organization

DELETE request for a given organizational unique identifier

 
 

Recommendations

The Affiliation API is used to link an edu-ID account to a user's account at an organization. For this reason, the organization needs the identifier of the edu-ID account swissEduID for the creation (CREATE) of the affiliation. The swissEduID is determined with the linking service. The implementation of the Affiliation API also requires the identifier swissEduID for updating (UPDATE) an affiliation.

There are 2 ways to get the identifier swissEduID to perform an affiliation update:

  1. Storage of the swissEduID in the local directory.
  2. Determination of the swissEduID with the GET affiliation method.

If the swissEduID is stored (method 1), a reconciliation process must be implemented to update the swissEduID when duplicates are merged. For this reason, method 2 is preferred in many cases and the swissEduID is discarded immediately after the linking is completed.