Аутентификация с помощью API-ключей¶
Все запросы к REST API платформы PWS должны быть аутентифицированы. Для этого используются статические API-ключи, которые передаются в заголовке Authorization каждого запроса в формате Bearer-токена.
Пошаговое руководство¶
Процесс получения доступа к API состоит из двух шагов: сначала вы создаете сервисный аккаунт, а затем получаете для него API-ключ.
Перед началом
Убедитесь, что в проекте создано приложение с экземпляром — сервисный аккаунт привязывается к конкретному экземпляру.
Шаг 1: Создайте сервисный аккаунт¶
Сервисный аккаунт — это специальная учетная запись для ваших приложений и сервисов, которая позволяет им проходить аутентификацию и взаимодействовать с API платформы.
- В навигационном меню проекта перейдите в раздел Сервисные аккаунты.
- Нажмите Создать аккаунт.
- Заполните основные данные:
- Название — понятное имя для идентификации аккаунта
- Описание — опционально, для пояснения назначения
- Настройте доступы:
- Экземпляр приложения — определяет, к какому экземпляру и окружению будет иметь доступ аккаунт. Его невозможно изменить после создания.
- Уровень доступа — выберите одну или несколько ролей. Роли можно изменить позже.
- Нажмите Создать.
Шаг 2: Получите и сохраните API-ключ¶
При создании сервисного аккаунта для него автоматически генерируется первый API-ключ. Он отображается в модальном окне сразу после создания аккаунта.
Скопируйте и сохраните ваш ключ немедленно
Секретная часть API-ключа (Секретный ключ) отображается только один раз. Обязательно скопируйте и сохраните его в надежном месте. Платформа не хранит его в открытом виде, и посмотреть его снова будет невозможно.
Использование ключа в запросах¶
Для аутентификации передавайте ваш Секретный ключ в заголовке Authorization с префиксом Bearer.
curl --request POST \
--url https://<DOMAIN>/v1/configs \
--header "Authorization: Bearer <YOUR_API_KEY>" \
--header "Content-Type: application/json"
import requests
api_key = "YOUR_API_KEY"
url = "https://<DOMAIN>/v1/configs"
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
response = requests.post(url, headers=headers)
print(response.json())
const fetch = require('node-fetch'); // Для Node.js
const apiKey = 'YOUR_API_KEY';
const url = 'https://<DOMAIN>/v1/configs';
const headers = {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
};
fetch(url, { method: 'POST', headers: headers })
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error('error:' + err));
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
class ApiClient
{
static async Task Main(string[] args)
{
var apiKey = "YOUR_API_KEY";
var url = "https://<DOMAIN>/v1/configs";
using (var client = new HttpClient())
{
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", apiKey);
var response = await client.PostAsync(url, null);
if (response.IsSuccessStatusCode)
{
var content = await response.Content.ReadAsStringAsync();
Console.WriteLine(content);
}
}
}
}
package main
import (
"fmt"
"io/ioutil"
"log"
"net/http"
)
func main() {
apiKey := "YOUR_API_KEY"
url := "https://<DOMAIN>/v1/configs"
req, err := http.NewRequest("POST", url, nil)
if err != nil {
log.Fatalf("Ошибка при создании запроса: %v", err)
}
req.Header.Set("Authorization", "Bearer "+apiKey)
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
log.Fatalf("Ошибка при выполнении запроса: %v", err)
}
defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
log.Fatalf("Ошибка при чтении ответа: %v", err)
}
fmt.Println(string(body))
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class ApiClient {
public static void main(String[] args) throws Exception {
String apiKey = "YOUR_API_KEY";
String url = "https://<DOMAIN>/v1/configs";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Authorization", "Bearer " + apiKey)
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response =
client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}
Не забудьте заменить плейсхолдеры
В примерах выше замените <YOUR_API_KEY> на ваш реальный Секретный ключ.
В параметре <DOMAIN> указывается адрес вашего сервера. В зависимости от типа вашей установки, это может быть:
- On-premises / Private Cloud: ваш корпоративный домен
- SaaS: версия в разработке (домен будет предоставлен после выпуска)
Управление ключами и безопасность¶
Правильное управление API-ключами — критически важный аспект безопасности вашего приложения.
Хранение ключей¶
Никогда не храните API-ключи в открытом виде в коде или системе контроля версий. Используйте безопасные методы:
- Переменные окружения на вашем сервере.
- Системы управления секретами (например, HashiCorp Vault, AWS Secrets Manager).
Ротация ключей¶
Для минимизации рисков рекомендуется периодически проводить ротацию ключей. Процесс состоит из следующих шагов:
- Создайте новый API-ключ. Для этого:
- На странице Сервисные аккаунты выберите нужный аккаунт.
- Нажмите на иконку редактирования рядом с названием аккаунта.
- Перейдите на вкладку API-ключи и нажмите Создать API-ключ.
- Дайте ключу осмысленное Описание и не забудьте скопировать
Секретный ключ.
- Обновите ваше приложение, чтобы они использовали новый ключ.
- Убедитесь, что все сервисы работают стабильно с новым ключом.
- Удалите старый ключ в интерфейсе платформы, чтобы он больше не мог быть использован.
Принцип наименьших привилегий¶
Один сервис — один сервисный аккаунт
Для максимальной изоляции и безопасности мы настоятельно рекомендуем создавать отдельный сервисный аккаунт для каждого сервиса или приложения.
Это позволяет:
- Изолировать доступ: Отзывать и ротировать ключи для одного сервиса, не затрагивая работу остальных.
- Гибко управлять правами: Назначать разные роли разным сервисным аккаунтам.
- Упростить аудит: Легко отслеживать, от какого сервиса приходят запросы.