API Specification

SWITCH edu-ID provides an API that can be queried by registered services. The API is REST/JSON based and provides a few very limited functions needed by AAI services which allow SWITCH edu-ID users. The SWITCH edu-ID team then will evaluate your request and provide you with an individual set of credentials to query the API.

How to get Access to the API?

In order to get access to the API, please write an e-mail to and mention why your application could benefit from the API.

How to query the API?


The API has to be queried with standard HTTP requests via HTTPS. The content type is ignored, but preferrably it is "application/json".


All requests have to be authenticated with HTTP Basic authentication.

Request Format

Request to the API have to be made with standard HTTP methods. The following methods are currently supported:

  • GET: Retrieve whatever information is identified by the request URL.
  • POST: Add some information.
  • PUT: Update a specified object.

The generic format of the request URL is:


  • #version#: The version number of the API. Currently, only the version 1 ("v1") is supported.
  • #objectType#: Type of objects that the request is about
  • #object#: Specific (url-encoded) identifier for an object of #objectType#

An example request thus could be:
GET https://eduid.ch/api/v1/mail/john.doe%40example.org

Request Types

The following objectTypes are currently implemented:

  • mail: E-mail address

Response Format

All responses (including errors) are returned as JSON objects.
The content-type of the HTTP response is "application/json". The character encoding is "UTF-8".
If an operation is successfull, the HTTP response code 200 is returned. Otherwise, one of the HTTP error codes below is returned.


Standard HTTP Error Codes are used to indicate errors. In particular the following error codes are supported.

  • 400 Bad request: The request had bad syntax or was inherently impossible to be satisfied.
  • 401 Unauthorized: The client has not authenticated or the credentials are not valid.
  • 403 Forbidden: The request is for something forbidden. Authorization will not help.
  • 404 Not found: The server has not found anything matching the URI given.
  • 500 Internal Error: The server encountered an unexpected condition which prevented it from fulfilling the request.
  • 501 Not implemented: The server does not support the facility required.

In addition to the standard HTTP error code, a JSON object will be returned. It has the format of.


    "error": {
        "code": #HTTP-ERROR-CODE#,
        "message": "#API-ERROR-MESSAGE#" 

An example error thus would be:

HTTP/1.1 404 Not Found

    "error": {
        "code": 404,
        "message": "E-mail address inexistent@email.address.org is not yet associated with a SWITCH edu-ID user." 

Supported Queries:

  • GET /api/#version#/mail/#object#
    Example query: GET https://eduid.ch/api/v1/mail/johnd%40gmail.com
    Description: Can be used to check if a particular email address given as #object# is already associated with a SWITCH edu-ID user or not.
    Important: The returned primary email address should exclusively be used for service-internal purposes like account matching. It should not be used to contact users, because they have not given their permission.
    Response: An error with code 404 will returned if the email address is not known. Otherwise, the HTTP response code 200 is returned as well as JSON object containing the primary email address:
        "mail": "#PRIMARY-EMAIL-ADDRESS#",
        "givenName": "#FIRST-NAME#",
        "surname": "#LAST-NAME#" 
    Thus an example response would be:
        "mail": "john.doe@example.org",
        "givenName": "John",
        "surname": "Doe" 
  • PUT /api/#version#/mail/#object# or PUT /api/#version#/swissEduID/#swissEduID#
    Body arguments:
        "lastLoginTime": "#UTC timestamp of format YYYYMMDDTHHMMSSZ#",
        "entityID": "#SP-ENTITY-ID#" 

    Mandatory arguments: lastLoginTime
    Example query: PUT https://eduid.ch/api/v1/mail/john.doe%40example.org or PUT https://eduid.ch/api/v1/swissEduID/12345678-b62c-44f5-87ff-f8d828a92334
        "lastLoginTime": "20161215T145649Z",
        "entityID": "https://attribute-viewer.switch.ch/shibboleth" 

    Description: Can be used to update a particular field of the user with the given email address or edu-ID identifier.
    Response: If the operation is successful, the HTTP response code 200 is returned with an empty JSON array.



  • PUT /api/#version#/swissEduID/#swissEduID#/affiliations
    Body arguments:
        "entityID":"#IdP entityID#",
        "validFrom":"#Optional RFC 3339 time stamp#" 

    Mandatory arguments: entityID
    Example query: PUT /api/v1/swissEduID/12345678-b62c-44f5-87ff-f8d828a92334/affiliations

    Description: This request is used to trigger (immediately or up to 15min after validFrom time) an attribute query for the user with the given edu-ID Identifier value to the Attribute Authority specified by entityID. If the attribute query is successful (=user attributes are returned by the organisation for this user), then a new current affiliation is for this user, which means that his data is updated daily with another attribute query. This request typically will be used by organisations when new students or employees join the organisations. Students/employees then first create an edu-ID account, which the organisation gets the edu-ID identifier for. Using the edu-ID identifier an organisation then can use this request to let the edu-ID service know that the given edu-ID user has a current affiliation to the organisation. EntityID that can be used in request is bound to the user that authenticated at the API. More information on the page that describes how to create new affiliation for a user.
    Response: If no valid From is set (=immediate Attribute Query), then the HTTP response code is 200 if the Attribute Query was successful but did not return any attributes, HTTP response code is 201 if the Attribute Query was successful and attributes were returned (=new current affiliation was created). If validFrom is set (and in the future), the HTTP response code is 202 if the request is valid and will be executed at the given validFrom date. In all cases the JSON response will be empty.