Токены
Краткий обзор
- Сравните типы токенов для скриптов, локальной разработки, тестирования и интеграций в рабочей среде.
- Узнайте, где создаются и отзываются токены и почему их значения необходимо сохранять в безопасном месте при создании.
- Разберитесь в ограничениях областей доступа и сроках действия токенов, а также узнайте, как с помощью токенов обновления получать краткоживущие токены доступа.
Токены — это учетные данные, используемые для авторизации запросов к API Altium 365. Все запросы к API должны содержать действительный токен в заголовке Authorization.
Токены создаются в вашем рабочем пространстве в разделе Admin → Developer. Создавать токены могут только администраторы рабочего пространства.
Типы токенов
Доступны два типа токенов, которые различаются способом использования и компромиссами в отношении безопасности.
Долгоживущий токен доступа
Единственный набор учетных данных, который используется непосредственно как Bearer-токен в запросах к API. Срок его действия задается при создании и может составлять до 1 года.
Authorization: Bearer {token}
Это более простой вариант: одно значение, используемое напрямую. Он хорошо подходит для скриптов, автоматизации и локальной разработки, где простота использования важнее ротации учетных данных.
Основное ограничение заключается в том, что значение токена не меняется на протяжении всего срока его действия. В случае раскрытия токен остается действительным до истечения срока действия или отзыва вручную.
Токен обновления
Более безопасный вариант, при котором долгоживущие учетные данные отделены от краткоживущих, используемых в запросах к API. При создании вы получаете три значения:
-
Client ID – идентифицирует клиент токена
-
Client secret – аутентифицирует клиент токена
-
Refresh token – долгоживущие учетные данные
Вы обмениваете их на краткоживущий access token, обращаясь к конечной точке выдачи токенов. Именно токен доступа используется в запросах к API. Когда срок его действия истекает, вы запрашиваете новый с помощью того же токена обновления.
Срок действия токена обновления настраивается и может составлять до 1 года. Выдаваемые с его помощью токены доступа имеют короткий срок действия.
Этот подход лучше подходит для интеграций в производственной среде:
-
Учетные данные, передаваемые с каждым запросом к API (токен доступа), имеют короткий срок действия
-
Долгоживущий секрет (токен обновления) остается в вашем защищенном хранилище и никогда не передается непосредственно в API
Порядок обмена токенов описан в разделе Использование токена обновления.
Выбор типа токена
|
Долгоживущий токен доступа |
Токен обновления |
Количество учетных данных |
1 (токен доступа) |
3 (идентификатор клиента + секрет клиента + токен обновления) |
Учетные данные для запросов к API |
Сам токен |
Краткоживущий токен доступа (получаемый путем обмена) |
Ротация |
Вручную |
Автоматически путем обмена |
Лучше всего подходит для |
Скриптов, локальной разработки, тестирования |
Интеграций в производственной среде |
Области доступа
Каждый токен связан с набором OAuth scopes, определяющих, какие операции API он может авторизовать. Области доступа задаются при создании токена и не могут быть изменены впоследствии.
Полный список доступных областей доступа и их соответствие возможностям API см. в разделе Области доступа OAuth.
Срок действия токена
Для обоих типов токенов срок действия задается при создании и может составлять до 1 года. Автоматическое продление не предусмотрено: по истечении срока действия токена необходимо создать новый.
Для токенов обновления этот срок относится к самому токену обновления. Выдаваемые с его помощью токены доступа имеют более короткий фиксированный срок действия — 1 час.
Отзыв токена
Токены можно в любой момент отозвать в разделе Admin → Developer. Отзыв немедленно делает токен недействительным: любые запросы к API с этим токеном будут завершаться ошибкой авторизации.