In English

Stuudium

≡ Sisukord

Stuudiumi API

Kasutaja tuvastamine Stuudiumi kontoga

Oma rakenduse registreerimisel kasutaja tuvastamise API kasutamiseks pead edastama ka aadressi, kuhu kasutaja pärast autentimist tagasi suunatakse (näiteks: https://example.com/autendi/stuudium).

Autentimisprotsessi kirjeldus:

1.

Sinu rakendus suunab kasutaja aadressile https://api.ope.ee/v1.1/authenticate?client_id=CLIENT_ID

Kui soovid kasutaja kohe suunata valitud kooli lehele, lisa aadressile subdomain=kooliaadress parameeter. Näiteks kui soovitud kooli Stuudium asub aadressil demo.ope.ee, suuna kasutaja autentimiseks aadressile https://api.ope.ee/v1.1/authenticate?client_id=CLIENT_ID&subdomain=demo

Autentimispäringuga võid kaasa saata ka state parameetri, mis tagastatakse (punktis 3 kirjeldatud viisil) sinu rakendusele pärast edukat autentimist. (Näidispäring .../authenticate?client_id=RAKENDUS&state=suvaline-v22rtus)

NB! Isegi kui kasutad suunamisel konkreetse kooli tähist, võib kasutaja sisse logida mõne teise kooli kontoga. St. punktis 5.1 kirjeldatud laiendatud autentimise puhul pead alati kontrollima vastuses sisalduvat client väärtust.

2.

Kasutaja tuvastab ennast Stuudiumi lehel ja lubab andmetele ligipääsu

3.

Kasutaja suunatakse tagasi aadressile https://sinu-rakenduse-callback-url?token=TOKEN. (Näiteks: https://example.com?token=123456)

Ku saatsid autentimispäringut sooritates ka state parameetri, sisaldub see ka vastuses. (Näiteks: https://example.com?token=123456&state=suvaline-v22rtus)

Kui kasutaja andmetele ligipääsu ei anna, suunatakse ta tagasi aadressile https://sinu-rakenduse-callback-url?error=access_denied. (Kui saatsid ka state parameetri, lisatakse see aadressile. Nt: ...?error=access_denied&state=suvaline-v22rtus

4.

Sinu rakendus pärib Stuudiumist vastava token-iga kasutaja andmeid:

https://api.ope.ee/v1.1/authenticate/verify?token=TOKEN

Näidis:

GET /v1.1/authenticate/verify?token=123456
Host: api.ope.ee
Authorization: [Vaata alalehte “API päringute autentimine”]

5.

Kui TOKEN on kehtiv, vastab Stuudium kasutaja andmetega JSON formaadis

{
    "idcode": "31122331234", // võib olla tühi
    "name_first": "Eesnimi",
    "name_last": "Perekonnanimi"
}

Kui TOKEN on kehtiv, ja sinu rakendusel on õigused lugeda laiendatud autentimisinfot, vastab Stuudium kasutaja andmetega JSON formaadis

{
"id": "muutumatu-kasutaja-id-string, näiteks 'test-123'",
"client": {
    "id": "kooli-tähis-1 (kui kooli aadress on 'test.ope.ee', on tähis 'test')",
    // kontrolli kindlasti, kas tähis vastab oodatud kooli tähisele. Kui rakendus on aktiivne mitmele koolile korraga, võib sisse logida ka mõne teise kooli kasutaja.
    "label": "Tallinna 156. Keskkool"
},
"idcode": "31122331234", // võib olla tühi
"name_first": "Eesnimi",
"name_last": "Perekonnanimi"
}

5.1

Kui sinu rakendusel on õigused lugeda laiendatud autentimisinfot koos õpilaste andmetega, vastab Stuudium kasutaja andmetega JSON formaadis:

{
"id": "muutumatu-kasutaja-id-string, näiteks 'test-123'",
"client": {
    "id": "kooli-tähis-1 (kui kooli aadress on 'test.ope.ee', on tähis 'test')",
    // kontrolli kindlasti, kas tähis vastab oodatud kooli tähisele. Kui rakendus on aktiivne mitmele koolile korraga, võib sisse logida ka mõne teise kooli kasutaja.
    "label": "Tallinna 156. Keskkool"
},
"group": "2015b", // klassi tähis, kui autentimise sooritanud kasutaja on õpilane. Väli võib olla tühi või vastusest puududa
"is_student" true, // kas kasutaja on õpilane (kasutajal võib korraga olla mitu rolli). Väli võib vastusest puududa
"is_teacher": false, // kas kasutaja on õpetaja(kasutajal võib korraga olla mitu rolli). Väli võib vastusest puududa
"is_parent": true, // kas kasutaja on lapsevanem (kasutajal võib korraga olla mitu rolli). Väli võib vastusest puududa
"idcode": "31122331234", // Väli võib olla tühi või vastusest puududa
"name_first": "Eesnimi",
"name_last": "Perekonnanimi",
"students": [ // väli eksisteerib vaid kasutajal, kellega on seotud 1 või enam õpilast. Õpilase puhul sisalduvad siin ka õpilase enda andmed.
    {
        "id": "muutumatu-kasutaja-id-string, näiteks 'test-123'",
        "client": {
            "id": "kooli-tähis-1",
            "label": "Tallinna 156. Keskkool",
        },
        "group": "2015b", // klassi tähis, kui tegu on õpilasega
        "idcode": "31122331234", // võib olla tühi
        "name_first": "Eesnimi",
        "name_last": "Perekonnanimi"
    },
    {
        // teise, kolmanda, jne jne õpilase andmed
    }
]
}

TOKEN kehtib vaid ühe korra; st. toimib vaid esimene päring /authenticate/verify aadressile.

Välja logimine

Kui sinu rakendusele on antud vastavad õigused, sisaldub (edukas) /authenticate/verify vastuses ka parameeter logout_url. See on (https) aadress, kuhu saad kasutaja suunata Stuudiumist välja logimiseks.

{
    "...."
    "name_last": "Perekonnanimi",
    "logout_url": "https://ope.ee/logi/kasutaja/v2lja",
}

NB! logout_url võib olla iga kasutaja jaoks erinev ning ajas muutuv. St. ühe kasutaja jaoks saadud väljalogimisaadressi tohib kasutada vaid konkreetselt selle kasutaja jaoks.

Näidiskasutus:

  • kasutaja logib sinu rakendusse sisse
  • <kasutab sinu rakendust>
  • kasutamise lõppedes klõpsab sinu rakenduses "Logi välja" nuppu
  • sinu rakendus lõpetab kasutaja sessiooni
  • ja viimase sammuna suunab kasutaja logout_url aadressile.
  • kasutaja logitakse ka Stuudiumist välja, ja ta jõuab lõpuks tavapärasele Stuudiumi login lehele