Перейти к содержанию

GitFlic API

Получение токена доступа accessToken

Получение персонального кода

Получение персональный кода возможно двумя способами: - через GET-запрос - через POST-запрос, используя схему Basic auth

Получение персонального кода через GET-запрос

Для авторизации отправьте GET-запрос по адресу:

  • для SaaS:
https://oauth.gitflic.ru/oauth/authorize
  • для Self-hosted:
localhost:8080/oauth/authorize

Запрос принимает 4 обязательных параметра:

Параметр Тип Описание
scope Enum Список предоставляемых прав
client_id или clientId String ID клиента, который можно получить в настройках приложения Oauth
redirect_url или redirectUrl String URL, на который будет перенаправлен после запроса
state String Параметр, идентифицирующий конечного пользователя

Узнать clientID можно в настройках Oauth приложения.

Типы scope

Scope Описание
USER_READ Просмотр информации о пользователе
USER_WRITE Редактирование профиля пользователя
PROJECT_READ Просмотр информации о проектах пользователя
PROJECT_WRITE Создание проектов от лица пользователя
PROJECT_EDIT Редактирование существующих проектов пользователя
TEAM_READ Просмотр информации о командах пользователя
TEAM_WRITE Создание и изменение команд
COMPANY_READ Просмотр информации о компаниях пользователя
COMPANY_WRITE Создание и изменение компаний

Пример запроса:

https://oauth.gitflic.ru/oauth/authorize?scope=USER_READ,USER_WRITE,PROJECT_READ,PROJECT_WRITE,PROJECT_EDIT&client_id=973d8a-aaaa-aaaa-aaaa-f29ba163bb53&redirect_url=https://example.org/&state=12345

Получение JSON на обратный вызов авторизации

На URL обратного вызова авторизации redirect_url или в качестве ответа (зависит от метода авторизации) посылается JSON-объект следующей структуры:

Поле Тип Описание
code String Персональный код
state String Параметр, идентифицирующий конечного пользователя

Получение персонального кода через POST-запрос с Basic Auth

Данный способ доступен только в self-hosted версиях GitFlic

Для авторизации отправьте POST-запрос по адресу:

localhost:8080/api/oauth/authorize

Для заголовка Authorization необходимо предоставить зашифрованные с помощью base64 учётные данные в формате Basic-auth.

Запрос принимает 3 обязательных параметра:

Параметр Тип Описание
scope Enum Список предоставляемых прав (scope)
client_id String ID клиента, который можно получить в настройках приложения Oauth
client_secret String Секрет клиента, который можно получить в настройках приложения Oauth

Типы scope

Scope Описание
USER_READ Просмотр информации о пользователе
USER_WRITE Редактирование профиля пользователя
PROJECT_READ Просмотр информации о проектах пользователя
PROJECT_WRITE Создание проектов от лица пользователя
PROJECT_EDIT Редактирование существующих проектов пользователя

Пример запроса:

POST localhost:8080/api/oauth/authorize?scope=USER_READ,USER_WRITE,PROJECT_READ,PROJECT_WRITE,PROJECT_EDIT&client_id=973d8a-aaaa-aaaa-aaaa-f29ba163bb53&client_secret=dc2da15d-aaaa-aaaa-aaaa-d5d04c4fb325

Получение токена доступа

После успешного получения персонального кода можно получить токен доступа:

Для получения accessToken отправьте GET-запрос:

  • для SaaS:
https://oauth.gitflic.ru/api/token/access?code=<code>
  • для Self-hosted:
http://localhost:8080/api/token/access?code=<code>

code - это персональный код из предыдущих пунктов

Пример запроса:

https://oauth.gitflic.ru/api/token/access?code=e462eb8c-aaaa-aaaa-aaaa-d12cba0cb852

В ответе вы получите JSON-объект следующей структуры:

Поле Тип Описание
accessToken String Токен доступа к API
refreshToken String Токен для получения нового accessToken
expires String Дата истечения срока accessToken

Пример получаемого JSON-объекта:

{
    "accessToken": "868f3765-aaaa-aaaa-aaaa-13faw8a3ca68",
    "refreshToken": "cb4917e7-aaaa-aaaa-aaaa-9bb604b42e0c",
    "expires": "2023-01-12T15:45:01.961001"
}

Использование accessToken

Теперь вы можете использовать API, вставляя полученный токен в headers нашего запроса:

Authorization: token <accessToken>

Обновление токена доступа accessToken через refreshToken

Полученный вами accessToken потеряет актуальность в момент времени, указанный в поле expires. Для того, чтобы получить новый accessToken, используйте токен, указанный в поле refreshToken.

  • Отправьте POST-запрос:
https://oauth.gitflic.ru/api/token/refresh
  • В тело запроса просто поместите ваш refreshToken.

Ответ будет аналогичным тому, что и при первом получении accessToken.