API

External API

The eduBadges API is protected with OpenID Connect. In order to use the API an external client - a.k.a. Relying Party - will need a personal bearer access_token.

sequenceDiagram
    participant Relying Party
    participant OIDC-NG
    participant EB
    participant Institution IdP
    participant eduBadges
    Relying Party->>OIDC-NG: Authorization URL
    OIDC-NG->>EB: SAML request + WAYF
    EB->>Institution IdP: SAML request
    Institution IdP->>EB: SAML response
    EB->>OIDC-NG: SAML response
    OIDC-NG->>Relying Party: Code
    Relying Party->>OIDC-NG: Token endpoint
    Note right of Relying Party: Backend channel
    OIDC-NG->>Relying Party: Access token
    Relying Party->>eduBadges: Direct award API POST
    Note right of Relying Party: Course identifier, EPPN students
    Note right of eduBadges: Bearer token
    eduBadges->>OIDC-NG: Introspect token
    OIDC-NG->>eduBadges: Token user information
    eduBadges->>eduBadges: Lookup user
    Note right of eduBadges: Validate user permissions
    eduBadges->>eduBadges: Direct awarding
    eduBadges->>Relying Party: Response status
    Relying Party->>Relying Party: User feedback

Loading

To issue direct awards the Relying Party - a.k.a. SIS - will need to provide a course identifier to lookup the Badgeclass. This identifier needs to be linked to the Badgeclass prior before any direct awards can be issued.

sequenceDiagram
    participant Relying Party
    participant eduBadges
    Relying Party->>eduBadges: https://edubadges.nl/manage/badgeclasses/context/<course_identifier>?redirect_url=https%3A%2F%2Fsis.nl
    eduBadges->>eduBadges: Display Badgeclass-picker
    Note right of eduBadges: Store course-identifier
    eduBadges->>Relying Party: Redirect back to https://sis.nl
    Relying Party->>Relying Party: User feedback

Loading