Omniscol API — аутентификация токендері

Кілт және токен: екі бөлек нысан

Omniscol шатастыруға болмайтын екі нысанды ажыратады.

Кілт — Omniscol жағында сақталатын тұрақты нысан. Ол мыналарды біріктіреді:

• кездейсоқ жасалатын, қысқа, ашық идентификатор: тізімде дәл сол көрсетіледі, және ол тексерілетін кілтті көрсету үшін әр токенмен бірге жүреді;
• кез келген уақытта өзгертуге болатын сипаттамалық белгі;
• кез келген уақытта өзгертуге болатын міндетті емес жарамдылық мерзімінің аяқталу күні;
• серверде жасалатын, криптографиялық қол қою кілті ретінде қызмет ететін ұзын кездейсоқ құпия.

Идентификатор, белгі және жарамдылық мерзімі — әкімшілік ақпарат: идентификатор тек ашық сілтеме, құпия элемент емес. Ал құпия — қол қоюдың жалғыз материалы: кілт жасалғанда кездейсоқ түрде жасалады, сервер жағында қалады, өзгертілмейді және ешқашан көрсетілмейді не қайтарылмайды — кілт жасалғанда да, кілттер тізімінде де. Тіпті ол ағып кетсе де, токенді жасанды түрде жасауға жетпейді: қол қою оны есептік жазбаға тән тұзбен және Omniscol-дан ешқашан шықпайтын сервер құпиясымен біріктіреді.

Токен — кілттің құпиясымен қол қойылған дербес JWT (JSON Web Token). Дәл оны сыртқы жүйеге береді. Оның қол қойылған мазмұнында тиісті есептік жазба, рұқсат етілген қол жеткізу нүктелерінің тізімі, ол шыққан кілт және өзінің жарамдылық мерзімі бар.

Басқаша айтқанда: кілт қол қояды, токенге қол қойылады. Бір кілт бірнеше токенге қол қоя алады — бәрін бірдей құпиямен тексеруге болады, сондықтан кілт жойылса, бәрі бірге қайтарып алынады.

Omniscol токенді сақтамайды: оны жасайды, бір рет көрсетеді, содан кейін әр шақыру кезінде кілттің құпиясынан оның қолтаңбасын қайта құру арқылы қайта тексереді (HMAC SHA-256). Сондықтан токен көтерген ешбір рұқсатты бұл құпиясыз өзгертуге болмайды.

Токен жасау

Бөлісу экраны Premium есептік жазбаларында Әкімшілік модулінде Импорт/Экспорт бөлімінде қолжетімді. Жасау екі қадамнан тұрады: алдымен кілт жасалады, содан кейін осы кілттен токен жасалады.

1. Кілт жасау — түсінікті белгіні және қол жеткізу уақытша болса, жарамдылық мерзімінің аяқталу күнін енгізіңіз. Оның белгісі мен жарамдылық мерзімі кейін де өзгертілетін болады; қол қою құпиясы өзгертілмейді.
2. Токен жасау — кілтті таңдаңыз, рұқсат етілген қол жеткізу нүктелеріне құсбелгі қойыңыз, қажет болса токеннің өз жарамдылық мерзімінің аяқталу күнін таңдаңыз, содан кейін JWT жасаңыз.

Жасалған кезде Omniscol токенді бір рет қана көрсетеді. Оны дереу құпиялар менеджеріне көшіріңіз: ол енді қайта көрсетілмейді. Токеннің жарамдылық мерзімі оның қол қойылған мазмұнына жазылған: оны кейін өзгертуге болмайды. Бұл күнді өзгерту үшін жаңа токен жасаңыз.

Яғни бір-біріне тәуелсіз жарамдылық мерзімінің екі деңгейі бар:

• кілттің жарамдылық мерзімі — кілттер тізімінен өзгертіледі; ол аяқталғанда осы кілттен шыққан барлық токендер қабылданбайды (шақыру 401 қатесімен аяқталады);
• токеннің жарамдылық мерзімі — жасалған кезде белгіленеді, JWT-ге жазылады және кейін өзгертілмейді.

Рұқсат етілген қол жеткізу нүктелері

Токен тек жасалған кезде белгіленген қол жеткізу нүктелеріне ғана қол жеткізуге мүмкіндік береді: оның бүкіл API-ді қамтитынын ешқашан болжамаңыз. Рұқсат етілген тізім токенде жүреді және әр шақыру кезінде тексеріледі; рұқсат етілмеген қол жеткізу нүктесіне шақыру қабылданбайды (401).

Жеке қол жеткізу нүктелерінен басқа, таңдау тізімі модуль бойынша жылдам таңдауларды ұсынады:

• жеке модуль жолы оның барлық қол жеткізу нүктелеріне рұқсат береді;
• операция бойынша нұсқалар — оқу, өзгерту, құру, жою — модульді бір ғана шақыру түрімен шектейді.

Осылайша «Кесте [оқу]» белгісін қою әр қол жеткізу нүктесін бір-бірлеп белгілемей-ақ, бірде-бір жазуды ашпай, кестелердің барлық оқуына рұқсат береді. Мейлінше дәл болыңыз: интеграцияға қатаң қажет модульдер мен операцияларға ғана рұқсат беріңіз.

Токенді пайдалану

Токенді API-ге жіберудің екі әдеттегі жолы:

• HTTP тақырыбы: Authorization: Bearer <токен> (ұсынылады).
• Query string: ?auth=<токен> (түзету үшін ыңғайлы, бірақ HTTP журналдарында көрінеді — жұмыста болдырмаңыз).

curl мысалы, OpenAPI-дан алынған нақты қол жеткізу нүктесімен бейімдеңіз:

curl -H "Authorization: Bearer $TOKEN" \
  https://your-school.omniscol.com/api/<модуль>/<қол-жеткізу-нүктесі>

OpenAPI құжаттамасы

Импорт/Экспорт экраны есептік жазба үшін қолжетімді спецификацияны Swagger Editor-да ашатын OpenAPI 3.1 сілтемесін көрсетеді. Онда мыналарды табасыз:

• ашылған API қол жеткізу нүктелерінің тізімі,
• алмасылатын деректер схемалары,
• әдістер мен параметрлер,
• күтілетін жауаптар.

Спецификацияны есептік жазбаңыз аутентификациясыз тікелей береді:

• /api/guest/openapi.json — JSON пішіміндегі спецификация;
• /api/guest/openapi.yaml (немесе /api/guest/openapi?yaml=true) — сол мазмұн YAML пішімінде;
• /api/guest/school_schema.json — есептік жазба деректерінің JSON схемасы.

ЖИ көмекшіңізге арналған толық анықтама

Портал Omniscol анықтамасының барлығын ЖИ көмекшісіне (Claude жобасы, жеке GPT…) білім қоры болуға дайын бір мәтіндік файл ретінде жариялайды:

• omniscol.com/fr/llms-full.txt — Markdown пішіміндегі толық нұсқаулық, анықтаманың әр тілінде қолжетімді (/en/llms-full.txt, /de/llms-full.txt…);
• omniscol.com/llms.txt — ЖИ іздеу жүйелері автоматты түрде табатын llms.txt стандартындағы индекс.

Қол жеткізуді қайтарып алу

Қайтарып алу жеке токен деңгейінде емес, кілт деңгейінде жүргізіледі.

Экран токен жасау үшін пайдаланылған кілттерді тізеді. Кілтті жою оның қол қою құпиясын Omniscol жағынан өшіреді: содан бастап осы құпиядан туындаған ешбір қолтаңбаны тексеру мүмкін емес және осы кілттен шыққан токенмен жасалған кез келген шақыру 401 қатесімен аяқталады. Токендерді жарамсыз ететін — құпияның болмауы, қайтарып алу тізімі емес.

ІТ қызметі үшін екі салдар бар:

• Токенді бір-бірлеп қайтарып алу жоқ. Omniscol шығарылған JWT-лерді сақтамайды және оның біреуін жеке өшіре алмайды: бұрын жасалған токен өзінің жарамдылық мерзімі аяқталғанша немесе оның кілті жойылғанша не мерзімі өткенше жарамды болып қалады.
• Кілттің жарамдылық мерзімін өзгерту оның барлық токендеріне бірден әсер етеді: бұл күнді ерте қою кілттен шыққан барлық токендердің қол жеткізуін тоқтатады.

Ең жақсы тәжірибе: ағып кетті деп күдіктенген кез келген кілтті кідіртпей жойыңыз, содан кейін түсінікті белгімен ауыстыратын кілт жасаңыз.

Әр мақсат пен қолданысқа бір кілт

Қайтарып алу кілт бойынша жүргізілетіндіктен, әр интеграцияға бір кілт бөліңіз (бір сыртқы бағдарлама = бір кілт). Кілттің құпиясы тек өз токендеріне қол қояды: бұл кілтті жою тек тиісті интеграцияның қол жеткізуін жарамсыз етеді, қалғандарына тиіспейді.

Керісінше, бірнеше жүйе бөлісетін жалғыз кілт кез келген қайтарып алуды қатаң етеді: бұзылған кілтті жою оны пайдаланған барлық жүйені бірден өшіреді.

Қандай интеграциялар үшін

API әдетте мыналар үшін пайдаланылады:

• жеке ақпарат көрсету жүйелері (Omniscol-дың кірістірілген ақпарат тақталарынан тыс; Ақпарат тақталарын теңшеу бетін қараңыз),
• Omniscol мен басқа дереккөздерді біріктіретін сыртқы бақылау тақталары,
• ERP немесе бизнес ақпараттық жүйесімен коннекторлар немесе синхрондаулар,
• MCP сервері арқылы Omniscol-ды пайдаланатын MCP үйлесімді ЖИ агенттері; MCP — сыртқы ЖИ агентін қосу бетін қараңыз.

Анықталған үшінші тарап қызметіне жеткізілген қол жеткізу үшін (шектелген токен, пайдаланушының келісімі, клиентті өшіру арқылы қайтарып алынатын) Omniscol-дың OAuth2 серверін таңдаңыз: OAuth2 / OIDC (провайдер) бетін қараңыз.