Create Affiliation

Goal for the edu-ID API Request to Create a new Affiliation

It should be possible to create a new organisation affiliation for a given edu-ID user identified by his edu-ID identifier value. Issuing a request does not set the affiliation directly but instead triggers an attribute query (by edu-ID Attribute Aggregator) to the specified attribute authority. Only if that query is successful (= personal user attributes are returned), a new affiliation gets set.


Requests are authenticated with HTTP Basic Authentication. The logic should ensure that affiliations generally can only be triggered by an organisation for their own attribute authority. Some requests (e.g. from SWITCH) should also be allowed to trigger attribute queries for third party attribute authorities for administrative purposes.

General API Request Structure

In line with the existing API requests in the API Specification the proposal is to use the following structure for the request:

PUT /api/#version#/#objectType#/#object#/#subObjectType#

with the parameters:

PUT /api/#version#/swissEduID/#swissEduID#/affiliations

Parameters and Arguments:

  • #version#, mandatory:
    Version of the API, currently "v1"
  • #swissEduID#, mandatory:
    edu-ID identifier value for which to set the affilation
  • entityID, mandatory:
    Attribute Authorities's entityID to query.
    It must correspond to the value in the SWITCHaai federation metadata.
  • validFrom, optional:
    Date-time value (according to after which affiliation
    should be set. If provided, an asynchronous attribute query is initiated, otherwise a synchronous attribute query will be scheduled.

Request Description

There are two types of requests, synchronous and asynchronous.

Synchronous Requests

Sending synchronous requests (without the validFrom parameter) immediately results in an attribute query to be sent to the Attribute Authority of the given entity specified using using swissEduID as NameIdentifier.

Asynchronous Requests

Asynchronous requests contain a validFrom parameter whose date/time is in the future. The attribute query then is executed the same minute as the date/time provided indicates.
The attribute query is currently a SAML Attribute Query (but later may also be a direct LDAP query to a migrated organisation's LDAP server).

Example Request

PUT /api/v1/swissEduID/8d3a49fe-b62c-44f5-87ff-f8d828a9375b/affiliations


  • HTTP Code 200 OK and {}:
    If (in a synchronous) user account was found and request was triggered but no new affiliation was set
  • HTTP Code 201 Created and {}:
    If (in a synchronous) user account was found and request was triggered and a new current affiliation was created for the user
  • HTTP Code 202 Accepted and {}:
    If (in an asynchronous request with validFrom) user account was found and request was stored in message queue for later execution
  • HTTP Code 401 Unauthorized:
    If authentication information is missing
  • HTTP Code 403 Forbidden:
    If user is not allowed to send this type of request or if he is not allowed to trigger this affiliation query
  • HTTP Code 404 Not Found:
    If user account was not found.
  • HTTP Code 500 Internal Error:
    The server encountered an unexpected condition which prevented it from fulfilling the request (e.g. validFrom in past)

How to Make Request

Making requests to the edu-ID API is generally very simple and all that is needed is a web client. Therefore, one can use for example curl, which is available on all operating systems. The general curl command to set an affiliation then would look like:

curl -s -basic -u "${apiusername}:${apipassword}" -X PUT -H "Content-Type: application/json" -d "{\"entityID\":\"${entityID}\",\"validFrom\":\"${timestamp}\"}" "${apiurl}${swissEduID}" 

An example request to set an affilation now would look like:

curl -s -basic -u "ethz:1234abcde" -X PUT -H "Content-Type: application/json" -d '{"entityID":""}' "" 


An example request to set an affilation in the future could therefore look like:

curl -s -basic -u "ethz:1234abcde" -X PUT -H "Content-Type: application/json" -d "{\"entityID\":\"\",\"validFrom\":\"2018-06-26T14:01:21Z\"}" ""