Авторизация по OAuth 2.0

Авторизация по OAuth 2.0 нужна, если вы делаете сервис для других компаний и должны обращаться к API от их имени — с их согласия. Например, если пользователи вашей платформы рассчитываются друг с другом через Точку.

Совет

Если интеграция нужна только вашей компании и вы не предоставляете её своим пользователям — проще воспользоваться авторизацией по JWT-токену. Она быстрее в настройке. OAuth 2.0 выбирайте, когда действуете от имени клиентов.

В результате вы получите access_token — токен, который добавляете в заголовок каждого запроса. Весь путь ниже нужно пройти один раз; дальше вы только обновляете токен.

Как это работает

Разовая настройка:

Зарегистрируйте приложение — получите client_id и client_secret
Получите токен для работы с разрешениями
Задайте список разрешений — получите consent_id
Попросите клиента подтвердить разрешения — получите code
Обменяйте code на токены — получите access_token и refresh_token

Дальше в процессе работы:

Обновляйте токены каждые 24 часа по refresh_token.
При необходимости проверяйте токен.

Общий флоу работы в схеме

На схеме представлен общий флоу работы от первого запроса разрешений до получения результата. Пройти этот путь нужно только один раз, чтобы создать токен oAuth.

Разрешения

В авторизации OAuth участвуют два связанных списка прав, и важно их не путать:

scope — широкие области доступа. Передаются строкой через пробел в запросах токенов и в ссылке подтверждения: accounts, balances, customers, statements, sbp, payments, acquiring.
permissions — конкретные разрешения, которые клиент подтверждает при создании списка разрешений (consent): ReadBalances, ReadStatements, MakeAcquiringOperation и другие.

Проще говоря, scope задаёт, к каким сервисам приложение просит доступ, а permissions — точный перечень операций внутри них.

Инфо

Следите, чтобы список scope был одинаковым во всех запросах одного флоу. Полный список разрешений (permissions) с описанием — на странице метода Работа с разрешениями.

Шаг 1. Зарегистрируйте приложение

Если у вашей компании ещё нет счёта в Точка Банке, оставьте заявку на сайте. Мы свяжемся в течение 2 рабочих дней и отправим нужные данные на почту.

Если вы уже работаете с Точка Банком, зарегистрируйте приложение в интернет-банке: раздел «Интеграции и API» → «Подключить». Нажмите «Подключить OAuth» и укажите название приложения, ссылку на него и компанию.

В ответ вы получите client_id и client_secret — с ними будете запрашивать данные.

Шаг 2. Получите токен для работы с разрешениями

Пройти oAuth авторизацию по принципу client_credentials. Это способ, когда приложение авторизуется само от себя, а не от имени пользователя. Если читать название буквально: по учётным данным клиента, где клиент = ваше приложение.

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

curl --request POST 'https://enter.tochka.com/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=test_app' \
--data-urlencode 'client_secret=test_secret' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=accounts balances customers statements sbp payments acquiring'

Пример ответа:

{
    "token_type": "bearer",
    "access_token": "p6awaKAleytQh6mKc61vXd22YniDerme",
    "expires_in": 86400
}

Шаг 3. Задайте разрешения

Создайте список разрешений (consent), которые вы запрашиваете у клиента. Параметр expirationDateTime задаёт срок действия разрешений — если нужны бессрочные, не передавайте его.

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

curl --request POST 'https://enter.tochka.com/uapi/v1.0/consents' \
--header 'Authorization: Bearer p6awaKAleytQh6mKc61vXd22YniDerme' \
--header 'Content-Type: application/json' \
--data-raw '{
  "Data": {
    "permissions": [
      "ReadAccountsBasic",
      "ReadAccountsDetail",
      "MakeAcquiringOperation",
      "ReadAcquiringData",
      "ReadBalances",
      "ReadStatements",
      "ReadCustomerData",
      "ReadSBPData",
      "EditSBPData",
      "CreatePaymentForSign",
      "CreatePaymentOrder",
      "ManageWebhookData",
      "ManageInvoiceData"
    ],
    "expirationDateTime": "2030-10-03T00:00:00+00:00"
  }
}'

В ответе придёт consentId — он понадобится на следующем шаге. Список разрешений создаётся со статусом AwaitingAuthorisation - ожидает подтверждения клиента.

Шаг 4. Получите подтверждение клиента

Сформируйте ссылку для подтверждения разрешений и перенаправьте на неё клиента. В параметрах передайте:

client_id — идентификатор вашего приложения.
response_type — тип ответа, всегда code.
state — произвольная строка. Вернётся в ответе — помогает связать запрос с ответом и защищает от подмены.
redirect_uri — адрес, на который вернём клиента после подтверждения. Должен совпадать с зарегистрированным при создании приложения.
scope — области доступа через пробел.
consent_id — идентификатор разрешения из ответа на шаге 3.

Пример ссылки:

https://enter.tochka.com/connect/authorize?client_id=test_app&response_type=code&state=Vuihvsds&redirect_uri=http://localhost:8000/&scope=accounts%20balances%20customers%20statements%20sbp%20payments&consent_id=705ba15f-a109-4156-bb7f-50c21413c158

Клиент подтверждает разрешения, и мы возвращаем его на ваш redirect_uri с параметром code.

Шаг 5. Обменяйте код на токены

Поймайте клиента на redirect_uri и обменяйте полученный code на токены:

curl --request POST 'https://enter.tochka.com/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=test_app' \
--data-urlencode 'client_secret=test_secret' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'scope=accounts balances customers statements sbp payments' \
--data-urlencode 'code=<полученный code>' \
--data-urlencode 'redirect_uri=http://localhost:8000/'

Пример ответа:

{
    "access_token": "JlvB7rgB0Q9vuuh0YNVQ4hBkGChIqovR",
    "refresh_token": "ViYnf8sDILwKpvUMcIQJEqCYy88zW1ys",
    "token_type": "bearer",
    "expires_in": 86400,
    "state": "Vuihvsds",
    "user_id": "b00b0f00-00b0-00cd-a0e0-642162432000"
}

Важно

Время жизни code — 5 минут. Если вы не успели обменять code на токены, то вернитесь к шагу 4 и повторите его.

Важно

Время жизни access_token — 24 часа, refresh_token — 30 дней. Обновляйте токены каждые 24 часа, используя последний полученный refresh_token.

Шаг 6. Обновляйте токены

Чтобы получить новую пару токенов, выполните запрос с grant_type=refresh_token:

curl --request POST 'https://enter.tochka.com/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=test_app' \
--data-urlencode 'client_secret=test_secret' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=ViYnf8sDILwKpvUMcIQJEqCYy88zW1ys'

В ответе придёт новая пара access_token и refresh_token. Дальше обновляйте токены уже по новому refresh_token.

Как использовать токен

Добавляйте access_token в заголовок авторизации каждого запроса:

Authorization: Bearer <access_token>

Если запрос относится к конкретной компании, дополнительно передавайте её идентификатор в заголовке customerCode. Запросить список компаний клиента можно методом Get Customers List.

Как проверить токен

Этот шаг необязательный. Однако если вам нужно проверить аутентификацию клиента по токену, вызовите introspect. В ответе придёт JWT-токен, в котором зашифрованы customerCode (sub) и client_id (aud).

curl --request POST 'https://enter.tochka.com/connect/introspect' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'access_token=dnjsndamklcmda8n3m2jkndsa76'

Как это работает​

Общий флоу работы в схеме​

Разрешения​

Шаг 1. Зарегистрируйте приложение​

Шаг 2. Получите токен для работы с разрешениями​

Шаг 3. Задайте разрешения​

Шаг 4. Получите подтверждение клиента​

Шаг 5. Обменяйте код на токены​

Шаг 6. Обновляйте токены​

Как использовать токен​

Как проверить токен​