Affiliations API

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

The affiliation API implements the organization push interface. 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

The examples below are simplified and illustrate the basic operations with the Affiliation-API. For details refer to the affiliation API doc.

Create a new affiliation for a user who already has an edu-ID identity and whose edu-ID identifier swissEduId is known. Note that the organizational unique identifier externalId identifies the affiliation, and is defined by the API client (the organization). It corresponds to the unique identifier in SWITCHaai.

POST /scim/Affiliations/
{
  "externalId":"859379@demouni.ch",
  "swissEduID": "c4d52189-9c62-4f41-b2a1-d3b6ce07dc7e",
  "swissEduPersonUniqueID": "859379@demouni.ch",
  "email": ["bsmith@demouni.ch"],
  "givenName": "Barbara",
  "surname": "Smith",
  "eduPersonAffiliation": ["student"],
  ...
}

The service responds with the newly created affiliation:

Location: https://api.eduid.ch/scim/Affiliations/859379%40demouni.ch
{
  "id":"859379@demouni.ch",
  "externalId":"859379@demouni.ch",
  "swissEduID": "c4d52189-9c62-4f41-b2a1-d3b6ce07dc7e",
  "swissEduPersonHomeOrganization": "demouni.ch",
  "swissEduPersonUniqueID": "859379@demouni.ch",
  "email": ["bsmith@demouni.ch"],
  "givenName": "Barbara",
  "surname": "Smith",
  "eduPersonAffiliation": ["student"],
  ...
}

Notice that the external identifier is also used as internal identifier for the affiliation, and that is has to be passed twice in externalId and swissEduPersonUniqueId.

The same response as above is sent as answer to a GET request with the externalId as affiliation identifier

GET /scim/Affiliations/859379%40demouni.ch

Overwrite an affiliation. A PUT method call to a user’s affiliation fully replaces the attributes of the existing affiliation. Previously set attributes that are not part of the PUT request will be deleted:

PUT /scim/Affiliations/859379%40demouni.ch
{
  "externalId":"859379@demouni.ch",
  "swissEduID": "c4d52189-9c62-4f41-b2a1-d3b6ce07dc7e",
  "swissEduPersonUniqueID": "859379@demouni.ch",
  "email": ["bsmith@demouni.ch"],
  "givenName": "Barbara",
  "surname": "Smith",
  "eduPersonAffiliation": ["student", "staff"],
  ...
}

Use the DELETE method to remove a current affiliation and transform it into a former affiliation.

DELETE /scim/Affiliations/859379%40demouni.ch