Mobile API

External API

The eduBadges Mobile API is protected with OpenID Connect. For the authorization of the user, we will use the OpenID authorization_code flow. The mobile app must be added as a public Relying Party in SURFconext with the authorization_code and refresh_token grant types and the correct scope: edubadges.nl/links. Also the email, sn, givenName and eduid attributes must be added to the ARP.

In order to ensure that the same eduid values are used for the mobile app and the eduBadges RP, we must add the metaData field coin:institution_guid to both relying parties with the same value. Also the same coin:institution_guid must be added to the Resource Server eduBadges, who is calling the introspect endpoint with the access_token in the Mobile API endpoint header. Otherwise, the eduid values are scoped per RP, resulting in two different users in the eduBadges backend.

When the mobile app is opened, then first an access_token must be obtained. See https://connect.test.surfconext.nl/oidc/.well-known/openid-configuration for the authorization and token urls. The mobile app must request the openid and eduid.nl/links and eduid.nl/mobile and eduid.nl/eppn scopes.

See for all mobile API endpoints the Swagger documentation on https://api-demo.edubadges.nl/api/schema/swagger-ui/#/mobile. All the endpoints require the following HTTP headers:

• x-requested-with, value is mobile
• content, value is application/json
• authorization, value is bearer: ${access_token}

sequenceDiagram
    participant MobileApp as Mobile App (RP)
    participant OIDC as OIDC-NG (OpenID Provider)
    participant EduBadges as eduBadges (Resource Server)

    Note over MobileApp: User initiates login

    MobileApp->>OIDC: Authorization Request (code_challenge, code_challenge_method)
    OIDC-->>MobileApp: Authorization Code (redirect)

    MobileApp->>OIDC: Token Request (code, code_verifier)
    OIDC-->>MobileApp: ID Token + Access Token + Refresh Token

    Note over MobileApp: Access Token acquired<br/>Start using Resource Server

    MobileApp->>EduBadges: GET /login (with Access Token)
    EduBadges-->>MobileApp: 200 OK (User session established)

    Note over EduBadges: Access Token expires after TTL

    MobileApp->>EduBadges: API Request with expired Access Token
    EduBadges-->>MobileApp: 401 Unauthorized (Token expired)

    Note over MobileApp: Needs new Access Token

    MobileApp->>OIDC: Refresh Token Request (with Refresh Token)
    OIDC-->>MobileApp: New Access Token (+ optional new Refresh Token)

    MobileApp->>EduBadges: Retry API Request (with new Access Token)
    EduBadges-->>MobileApp: 200 OK (Authorized)

Loading