API анықтамасы

Негізгі URL

Орта	URL
Өндірістік	https://api.hitkey.io

Аутентификация

Көптеген эндпоинттер Bearer токен арқылы аутентификацияны талап етеді:

Authorization: Bearer YOUR_TOKEN

Токендердің екі түрі пайдаланылады:

• API Bearer токендер — POST /auth/login-нен (тікелей API қолжетімділік үшін)
• OAuth access токендер — POST /oauth/token-нен (серіктес интеграциялар үшін)

Толық ақпарат үшін Токен түрлері қараңыз.

Жауап форматы

Барлық жауаптар JSON. Сәтті жауаптар деректерді тікелей қайтарады:

{
  "id": "uuid",
  "name": "Example"
}

Қате жауаптары мына негізгі форматты пайдаланады:

{
  "error": "Адамға оқылатын хабарлама",
  "code": "ERROR_CODE"
}

AdonisJS валидация қателері (HTTP 422) массив форматын пайдаланады:

{
  "errors": [
    {
      "message": "Validation failed",
      "rule": "required",
      "field": "email"
    }
  ]
}

Интерактивті құжаттама

Swagger UI мына мекенжайда қолжетімді:

Орта	URL
Өндірістік	https://api.hitkey.io/docs

OpenAPI спецификациясын /swagger.json мекенжайынан алуға болады.

Эндпоинттерге шолу

OAuth (/oauth)

Метод	Эндпоинт	Аутент.	Сипаттама
GET	/oauth/authorize	Иә	Авторизация кодын алу
POST	/oauth/token	Жоқ	Кодты / refresh токенді айырбастау
GET	/oauth/userinfo	OAuth	Пайдаланушы профилін алу (OIDC)
POST	/oauth/clients	Иә	OAuth клиент жасау
GET	/oauth/clients	Иә	OAuth клиенттер тізімін алу

Auth (/auth)

Метод	Эндпоинт	Аутент.	Сипаттама
POST	/auth/register/start	Жоқ	Тіркелуді бастау
POST	/auth/register/verify	Жоқ	Email кодын верификациялау
POST	/auth/register/password	Жоқ	Құпия сөзді орнату (автоматты кіру)
POST	/auth/register/resend	Жоқ	Верификация кодын қайта жіберу
POST	/auth/register/with-invite	Жоқ	Жоба шақыруы арқылы тіркелу
POST	/auth/login	Жоқ	Кіру
POST	/auth/logout	Иә	Шығу
GET	/auth/me	Иә	Ағымдағы пайдаланушы
PATCH	/auth/profile	Иә	Профильді жаңарту
POST	/auth/token/refresh	Жоқ	API токенді жаңарту
POST	/auth/password/forgot	Жоқ	Құпия сөзді қалпына келтіру сұрау
POST	/auth/password/reset	Жоқ	Құпия сөзді қалпына келтіруді аяқтау

2FA (/auth/2fa)

Метод	Эндпоинт	Аутент.	Сипаттама
GET	/auth/2fa/setup	Иә	TOTP орнату ақпаратын алу (QR код)
POST	/auth/2fa/enable	Иә	2FA қосу
POST	/auth/2fa/disable	Иә	2FA өшіру
POST	/auth/2fa/verify	Жоқ	Кіру кезіндегі TOTP тексеру

Электрондық пошталар (/auth/emails)

Метод	Эндпоинт	Аутент.	Сипаттама
GET	/auth/emails/	Иә	Барлық email-дер тізімі
POST	/auth/emails/	Иә	Email қосу
POST	/auth/emails/verify	Иә	Қосылған email-ді верификациялау
POST	/auth/emails/resend	Иә	Верификацияны қайта жіберу
PATCH	/auth/emails/:id/default	Иә	Әдепкі email-ді орнату
DELETE	/auth/emails/:id	Иә	Email-ді жою

Пайдаланушылар (/users)

Метод	Эндпоинт	Аутент.	Сипаттама
GET	/users/search	Иә	Email/ат/пайдаланушы аты бойынша пайдаланушыларды іздеу

Іздеу параметрлері:

Параметр	Түрі	Міндетті	Сипаттама
q	string	Иә	Іздеу сөзі (email, ат немесе пайдаланушы аты)
project_slug	string	Жоқ	Жоба контексті бойынша сүзу

Максимум 10 сәйкес пайдаланушыны қайтарады.

Жобалар (/projects)

Метод	Эндпоинт	Аутент.	Сипаттама
POST	/projects/	Иә	Жоба жасау
GET	/projects/	Иә	Жобалар тізімі
GET	/projects/:slug	Иә	Жобаны алу
PATCH	/projects/:slug	Иә	Жобаны жаңарту
DELETE	/projects/:slug	Иә	Жобаны жою
POST	/projects/:slug/join	Иә	Жобаға қосылу
DELETE	/projects/:slug/leave	Иә	Жобадан шығу

Жоба мүшелері (/projects/:slug/members)

Метод	Эндпоинт	Аутент.	Сипаттама
GET	/projects/:slug/members	Иә	Мүшелер тізімі
POST	/projects/:slug/members	Иә	Мүше қосу
PATCH	/projects/:slug/members/:id	Иә	Мүшені жаңарту
DELETE	/projects/:slug/members/:id	Иә	Мүшені алып тастау
POST	/projects/:slug/transfer-ownership	Иә	Иелікті беру

Шақырулар (/invites)

Метод	Эндпоинт	Аутент.	Сипаттама
GET	/invites/:token	Жоқ	Шақыруды қарау
POST	/invites/:token/accept	Иә	Шақыруды қабылдау

Денсаулық

Метод	Эндпоинт	Аутент.	Сипаттама
GET	/health	Жоқ	Денсаулық тексеру
GET	/docs	Жоқ	Swagger UI
GET	/swagger.json	Жоқ	OpenAPI спецификациясы