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

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


Токен доступа - access token, обеспечивает возможность взаимодействия с публичным API GitFlic. Получить этот токен можно двумя способами:

Создание токена через интерфейс

Для создания токена доступа через интерфейс необходимо:

  1. Перейти в профиль пользователя
  2. Перейти в раздел API токены
  3. Нажать кнопку Создать, указать название, дату окончания срока действия и набор прав

Токен, создаваемый через интерфейс, не имеет функции обновления - продление срока действия при помощи refresh token, в отличии от токена, создаваемого с помощью приложения Oauth.

Также, такой токен можно создать при помощи REST-API метода, используя аунтефикацию по схеме Basic Authentication.

Создание токена с помощью приложения Oauth

Токен, создаваемый при помощи приложения Oauth, имеет ограниченный срок действия - 1 месяц. Срок действия можно обновить, используя refresh token

Данный способ состоит из двух этапов:

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

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

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

Для получения персонального кода необходимо отправить GET-запрос по адресу:

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

Домен и порт для self-hosted версии могут отличаться.

В запросе необходимо передать следующие обязательные параметры:

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

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

clientID

Параметр 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&client_id=973d8a-aaaa-aaaa-aaaa-f29ba163bb53&redirect_url=https://example.org/&state=12345

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

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

Для получения персонального кода необходимо отправить POST-запрос по адресу:

localhost:8080/api/oauth/authorize

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

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

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

Параметр scope может содержать следующие права:

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

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

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

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

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

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

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

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

Для получения access token необходимо отправить GET-запрос:

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-объект следующей структуры:

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

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

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

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

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

Необходимо отправить POST-запрос, поместив в тело refreshToken:

https://oauth.gitflic.ru/api/token/refresh
  • для Self-hosted:
http://localhost:8080/api/token/refresh

В ответе придет JSON-объект, аналогичный ответу при получении access token.

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

Для взаимодействия с публичным API GitFlic необходимо указать полученный access token в заголовке запроса в следующей форме:

Authorization: token <accessToken>