> ## Documentation Index
> Fetch the complete documentation index at: https://docs.1unic.com/odatav4/llms.txt
> Use this file to discover all available pages before exploring further.

# Токены

> Доступ без учётной записи 1С: выпуск, передача, срок, отзыв, ограничение по IP

Токен даёт доступ к сервису `odatat` без учётной записи 1С. Его права определяет профиль, указанный при выпуске. Токены нужны для Power BI, Excel, внешних систем и браузерных клиентов.

## Формат и хранение

Токен — `o4_` и 72 символа base32 (360 бит). В базе (справочник `OData4_Токены`) хранится только его SHA-256, поэтому значение нельзя посмотреть повторно.

## Выпуск

На вкладке «Токены» формы «Настройки OData4» нажмите «Выпустить» и выберите профиль, срок и разрешённые IP. Форма **один раз** покажет значение токена и готовый адрес `…/hs/odatat/t/<токен>/v4/`. Сохраните его сразу.

<Frame caption="Вкладка «Токены»: кнопки «Выпустить», «Отозвать», «Продлить» и список выпущенных токенов">
  <img src="https://mintcdn.com/o-data-v4/8iesiGXq06VGcZxz/images/admin/settings-tokens.png?fit=max&auto=format&n=8iesiGXq06VGcZxz&q=85&s=bcf00a71e4b673a4877d2018a599a4b2" alt="Вкладка «Токены»: кнопки «Выпустить», «Отозвать», «Продлить» и список выпущенных токенов" width="1094" height="680" data-path="images/admin/settings-tokens.png" />
</Frame>

<Frame caption="Форма выпуска токена: имя, профиль, срок действия и разрешённые IP">
  <img src="https://mintcdn.com/o-data-v4/8iesiGXq06VGcZxz/images/security/token-issue.png?fit=max&auto=format&n=8iesiGXq06VGcZxz&q=85&s=42bdfb52bbd3fe46d9bb9a161b60dc84" alt="Форма выпуска токена: имя, профиль, срок действия и разрешённые IP" width="1094" height="274" data-path="images/security/token-issue.png" />
</Frame>

Из кода токен выпускает `OData4_Профили.ВыпуститьТокен`.

## Передача

Способы перечислены по старшинству:

<Tabs>
  <Tab title="Заголовок">
    ```http theme={null}
    GET /base-svc/hs/odatat/v4/Catalog_Контрагенты
    X-OData4-Token: o4_…
    ```

    Лучший вариант для интеграций: токен не попадает в адрес и в журнал веб-сервера.
  </Tab>

  <Tab title="Путь">
    ```
    https://server/base-svc/hs/odatat/t/o4_…/v4/
    ```

    Для Power BI и Excel. Они строят адрес `$metadata` от корня сервиса и теряют параметры, но сохраняют путь. Токен входит во все ссылки ответа: `@odata.context`, `@odata.nextLink`, `Location`, `OData-EntityId`.
  </Tab>

  <Tab title="Параметр">
    ```
    https://server/base-svc/hs/odatat/v4/Catalog_Контрагенты?token=o4_…
    ```

    `@odata.nextLink` переносит токен, только если он пришёл в адресе.
  </Tab>
</Tabs>

<Warning>
  Адрес с токеном, в пути или в параметре, остаётся в журнале веб-сервера. Журнал запросов OData4 токен не хранит: путь пишется без `/t/<токен>`, параметр `token` убирается, подстроки вида `o4_…` заменяются на `o4_***`.
</Warning>

## Срок, продление, отзыв

* Срок действия задаётся только будущей датой. Пустая дата — бессрочный токен.
* «Продлить» тоже принимает только будущую дату.
* **Отзыв окончателен.** Отозванный токен не продлевается и не включается обратно, нужен новый токен.
* Отзыв действует со следующего запроса.

Из кода — `OData4_Профили.ПродлитьТокен` и `OData4_Профили.ОтозватьТокен`. Они возвращают текст отказа, если операция невозможна.

## Ограничение по IP

«Разрешённые IP» — список, по одному значению в строке:

* адрес целиком, IPv4 или IPv6;
* подсеть IPv4 `a.b.c.d/длина`, длина от 0 до 32.

Подсети IPv6 не поддерживаются: `::1/128` не принимается, `::1` — принимается. Пустой список снимает ограничение по адресу. Список проверяется при записи.

### Адрес клиента за прокси

Адреса соединения у HTTP-сервиса 1С нет, поэтому адрес клиента берётся из заголовка, который ставит доверенный прокси. Настройки на вкладке «Аутентификация»:

| Настройка | Значение |
| - | - |
| Заголовок адреса клиента | `X-Forwarded-For` или `X-Real-IP` |
| Доверять заголовку адреса клиента | Флажок |
| Число доверенных прокси | По умолчанию 1 |

Адрес берётся **справа**. Прокси дописывает в конец `X-Forwarded-For` адрес, с которого к нему пришли, а всё, что левее, присылает клиент и может подделать. При N доверенных прокси адрес клиента — N-й справа. Если адресов меньше N, адрес не определён, и запрос отклоняется.

<CodeGroup>
  ```nginx nginx theme={null}
  proxy_set_header X-Real-IP $remote_addr;   # один адрес, N = 1
  # или
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  ```

  ```apache Apache без прокси theme={null}
  # в разделе публикации токенов: перезаписать заголовок адресом соединения (N = 1)
  RequestHeader set X-Forwarded-For "expr=%{REMOTE_ADDR}"
  ```
</CodeGroup>

<Warning>
  Токен с разрешёнными IP **без доверенного заголовка отвергается**. Ответ — `401` «Ограничение токена по адресу клиента не проверяется…». Настройки и форма выпуска предупреждают об этом.
</Warning>

## Токены продолжения

Флажок «\[Экспериментально] Токены продолжения»: ссылка `@odata.nextLink` несёт вместо токена одноразовый ключ `cont`, привязанный к токену, набору и параметрам запроса. Срок ключа задаётся в настройках. Использованные и просроченные ключи удаляет регламентное задание «Очистка OData4».

## Отказы

`401` называет причину: токен не найден, отозван, истёк или адрес не разрешён. Имя токена и адрес клиента в ответ не попадают, они пишутся в журнал регистрации (событие `OData4.Безопасность`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.