WORKSECTION

OAuth 2.0

Як працює OAuth 2.0

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.

Ця стаття була вам корисною? Так, дякую! Ні

Початкові налаштування OAuth 2.0

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

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

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

Ця стаття була вам корисною? Так, дякую! Ні

Код авторизації OAuth 2.0

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

https://worksection.com/oauth2/authorize
URL-адреса авторизації має містити обов'язкові параметри:

ПАРАМЕТР
ОПИС
client_id
client_id, отриманий при створенні додатку.
response_type
Налаштування відповіді, повернення коду авторизації. Завжди вказуємо значення code.
redirect_uri
URI, куди буде перенаправлена відповідь. URI має відповідати вимогам стандарту OAuth2 і використовувати протокол HTTPS.
state
Випадкова текстова стрічка, що буде включена у відповідь вашому додатку в кінці потоку OAuth. Основна ціль - запобігання підробки запитів CSRF.
scope
Дозволи OAuth допомагають вам точно налаштувати, до яких даних в Worksection ваш додаток буде мати доступи. Цей параметр передається у вигляді стрічок, розділених пробілом або комою. Список доступних областей видимості: projects_read, projects_write, tasks_read, tasks_write, costs_read, costs_write, tags_read, tags_write, comments_read, comments_write, files_read, files_write, users_read, users_write, contacts_read, contacts_write, administrative.
Ця стаття була вам корисною? Так, дякую! Ні

Обробка коду авторизації OAuth 2.0

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



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



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



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

Ця стаття була вам корисною? Так, дякую! Ні

Токен доступу OAuth 2.0

Дані для доступу можна отримати шляхом виконання 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 місяць.

Ця стаття була вам корисною? Так, дякую! Ні

Використання токену доступу OAuth 2.0

Кожен запит до 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 або отримати новий.

Ця стаття була вам корисною? Так, дякую! Ні

Оновлення токена доступу OAuth 2.0

Після того, як токен доступу стане недійсним, його потрібно оновити. Ви можете зробити це, використавши 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"
}
Запит оновлення повертає нові токен доступу та токен оновлення, що зробить старі токени недійсними.

Ця стаття була вам корисною? Так, дякую! Ні

Отримання інформації про користувача OAuth 2.0

Ви можете також використати 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" }

Ця стаття була вам корисною? Так, дякую! Ні
esc
или
Роздрукувати