Worksection API додатково використовує для авторизації протокол OAuth 2.0. Протокол платформи авторизації OAuth 2.0 описаний в  https://​datatracker​.ietf​.org/​d​o​c​/​h​t​m​l​/​r​f​c6749 . 

Ми підтримуємо поток коду авторизації зі стандарту Oauth.
Порядок авторизації OAuth 2.0:

Корисні матеріали:

1. Бібліотека SDK для спрощення роботи з нашим API.
2. Бібліотека OAuth 2.0 для зручної роботи з Worksection OAuth 2.0.
3. Колекції методів в Postman.

Для налаштування авторизації натисніть на аватарку, зайдіть в налаштування акаунту, розділ API . 

Для використання авторизації OAuth 2.0 вам потрібно зареєструвати та налаштувати застосунок Worksection API. У кожного додатку є свій унікальний client id та client secret, що будуть використані в потоці OAuth.

Вікно налаштування будь-якого додатку: 

Щоб почати процес авторизації, користувач має натиснути на посилання у вашому застосунку, яке направить його на URL:

https://worksection.com/oauth2/authorize

URL-адреса авторизації має містити обов'язкові параметри:

Після переходу по URL-адресі авторизації на першому етапі користувач перенаправляється на сторінку входу в Worksection, якщо він ще не виконав вхід: 

або ж на сторінку вибору користувача, якщо він вже був авторизований:

Після успішної авторизації користувач перенаправляється на сторінку підтвердження доступу:

Якщо користувач надав доступ на сторінці погодження, він буде перенаправлений на redirect_​uri з параметром code.
Зверніть увагу, що код авторизації дійсний протягом 10 хвилин.

Дані для доступу можна отримати шляхом виконання POST-запиту на URL-адресу токена з кодом авторизації:

https://worksection.com/oauth2/token

POST-запит повинен містити обов'язкові параметри:

ПАРАМЕТР	ОПИС
client_id	client_id, отриманий при створенні додатку.
client_secret	client_secret, отриманий при створенні додатку.
grant_type	Завжди вказуємо значення authorization_code.
code	Код авторизації, який ви отримали на попередньом кроці.
redirect_uri	URI, куди буде перенаправлена відповідь. URI має відповідати вимогам стандарту OAuth2 і використовувати протокол HTTPS.

Приклад CURL:

curl -X POST -d "client_id=<client_id>&client_secret=<client_secret>&grant_type=authorization_code&code=<authorization_code>&redirect_uri=<redirect_uri>"
https://worksection.com/oauth2/token 

Приклад відповіді:

{
    "token_type": "Bearer",
    "expires_in": 86400,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJh...",
    "refresh_token": "def502005534a202e9e8effa05cdbad564015604f34...",
    "account_url": "https://authorizeduseraccount.worksection.com"
}

Отримані access_token та refresh_token будемо використовувати в наступних запитах для доступу до API та оновлення access_token. Термін дії access_token - 24 години, термін дії refresh_token - 1 місяць.

Кожен запит до API через OAuth2 протокол має виконуватись по HTTPS з токеном доступу, який має бути переданий в header авторизації або ж в параметрі access_token. Для всіх запитів вам необхідно використовувати базовий URL:

https://youraccount.worksection.com/api/oauth2

Наприклад використання API-методу get_tasks для отримання завдань певного проекту:

curl -X GET -H "Authorization: Bearer <token_value>"
https://youraccount.worksection.com/api/oauth2?action=get_tasks&id_project=193

Ви отримаєте відповідь, схожу на:

{
    "status": "ok",
    "data": [
        {
            "name": "T0",
            "page": "/project/193/13036/",
            "status": null,
            "priority": "1",
            "user_from": "Marcus Wright",
            "user_to": "Marcus Wright",
            "from_me": 0,
            "to_me": 0,
            "date_added": "2023-03-10 16:41",
            "date_start": "2023-03-15",
            "date_end": "2023-03-23",
            "child": [
                {
                    "name": "T0.1",
                    "page": "/project/193/13036/13037/",
                    "status": null,
                    "priority": "1",
                    "user_from": "Marcus Wright",
                    "user_to": "Marcus Wright",
                    "from_me": 0,
                    "to_me": 0,
                    "date_added": "2023-03-10 16:41"
                }
            ]
        }
]
}

Кожен токен доступу дійсний протягом 24-х годин. Далі потрібно оновити його за допомогою refresh_token або отримати новий.

Після того, як токен доступу стане недійсним, його потрібно оновити. Ви можете зробити це, використавши refresh_token (що був отриманий в методі /oauth2/token) та відправивши POST-запит на URL:

https://worksection.com/oauth2/refresh

POST-запит має містити обов'язкові параметри:

ПАРАМЕТР	ОПИС
client_id	client_id, отриманий при створенні додатку.
client_secret	client_secret, отриманий при створенні додатку.
grant_type	Завжди вказуємо значення refresh_token.
refresh_token	Токен оновлення, що був отриманий в методі /oauth2/token.

Приклад CURL:

curl -X POST -d
"client_id=<client_id>&client_secret=<client_secret>&grant_type=refresh_token&refresh_token=<refresh_token>"
https://worksection.com/oauth2/refresh

Приклад відповіді:

{
    "token_type": "Bearer",
    "expires_in": 86400,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1...",
    "refresh_token": "def50200365724c970b6cea5eeecfed28...",
    "account_url": "https://authorizeduseraccount.worksection.com"
}

Запит оновлення повертає нові токен доступу та токен оновлення, що зробить старі токени недійсними.

Ви можете також використати access_token для отримання додаткової інформації про користувача, за потреби. Потрібно відправити POST-запит на URL:

https://worksection.com/oauth2/resource

POST-запит має містити обов'язкові параметри:

ПАРАМЕТР	ОПИС
client_id	client_id, отриманий при створенні додатку.
client_secret	client_secret, отриманий при створенні додатку.
access_token	Токен доступу, що був отриманий в методі /oauth2/token.

Приклад CURL:

curl -X POST -d
"client_id=<client_id>&client_secret=<client_secret>access_token=<access_token>"
https://worksection.com/oauth2/resource

Приклад відповіді:

{
    "id": "11",
    "first_name": "Valdemaar",
    "last_name": "Pupkoff",
    "email": "[email protected]",
    "account_url": "https://authorizeduseraccount.worksection.com"
}