Перейти к основному содержимому

Секреты

Управление Секретами через API​

Для безопасного управления конфиденциальными данными, такими как API-токены и пароли, вы можете использовать API для работы с секретами. Все операции доступны через эндпоинт /v1/secrets.

1. Структура данных​

Secret​

Это основной объект, представляющий секрет в системе. Он содержит метаданные, но не само значение секрета для безопасности.

ПолеТипОписаниеПример
idstringУникальный идентификатор секрета.sec123abc456
secret_namestringУникальное имя секрета в рамках организации. Максимум 100 символов.DATABASE_PASSWORD
secret_valuestringЗначение секрета. Присутствует только в ответах на запросы GET /v1/secrets/{secret_id}.my-secure-password
created_bystringИдентификатор пользователя, создавшего секрет.usr123def456
updated_bystringИдентификатор пользователя, который последний раз обновил секрет.usr789ghi012
created_atstring (date-time)Время создания секрета в формате ISO.2024-01-15T10:00:00Z
updated_atstring (date-time)Время последнего обновления секрета в формате ISO.2024-01-15T14:00:00Z

CheckSecret​

Этот объект связывает секрет с конкретной проверкой (Check). Он определяет, как секрет будет доступен в скрипте.

ПолеТипОписаниеПример
idstringУникальный идентификатор связи "проверка-секрет".cs123abc456
secret_idstringУникальный идентификатор секрета.sec123abc456
env_variablestringИмя переменной окружения, через которую секрет будет доступен в скрипте. Максимум 100 символов.DATABASE_PASSWORD
secretobjectОбъект секрета (без значения).{"id": "sec123abc456", "secret_name": "DATABASE_PASSWORD"}
created_atstring (date-time)Время создания связи в формате ISO.2024-01-15T10:00:00Z

2. API-эндпоинты​

Создание нового секрета​

Создаёт новый секрет с заданным именем и значением.

  • Эндпоинт: POST /v1/secrets
  • Тело запроса: 
    {
      "secret_name": "API_KEY",
      "secret_value": "your_super_secret_value"
    }
  • Ответ: 201 Created 
    {
      "id": "sec123abc456",
      "secret_name": "API_KEY",
      "created_by": "usr123def456",
      "updated_by": "usr123def456",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z"
    }

Получение списка секретов​

Возвращает список всех доступных секретов в организации. Значения секретов скрыты из соображений безопасности.

  • Эндпоинт: GET /v1/secrets
  • Параметры: Поддерживается пагинация.
    • page: Номер страницы.
    • page_size: Количество элементов на странице.
  • Ответ: 200 OK 
    {
      "secrets": [
        {
          "id": "sec123abc456",
          "secret_name": "API_KEY",
          "created_by": "usr123def456",
          "updated_by": "usr123def456",
          "created_at": "2024-01-15T10:00:00Z",
          "updated_at": "2024-01-15T10:00:00Z"
        }
      ],
      "pagination": {
        "page": 1,
        "page_size": 20,
        "total_pages": 1,
        "total_items": 2
      }
    }

Получение конкретного секрета​

Возвращает информацию по конкретному секрету, включая его значение.

  • Эндпоинт: GET /v1/secrets/{secret_id}
  • Параметры пути:
    • secret_id: Уникальный идентификатор секрета.
  • Ответ: 200 OK 
    {
      "id": "sec123abc456",
      "secret_name": "API_KEY",
      "secret_value": "your_super_secret_value",
      "created_by": "usr123def456",
      "updated_by": "usr123def456",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z"
    }

Обновление секрета​

Обновляет значение существующего секрета. Имя секрета не может быть изменено.

  • Эндпоинт: PATCH /v1/secrets/{secret_id}
  • Параметры пути:
    • secret_id: Уникальный идентификатор секрета.
  • Тело запроса: 
    {
      "secret_value": "new_super_secret_value"
    }
  • Ответ: 200 OK 
    {
      "id": "sec123abc456",
      "secret_name": "API_KEY",
      "secret_value": "new_super_secret_value",
      "created_by": "usr123def456",
      "updated_by": "usr789ghi012",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T14:00:00Z"
    }

Удаление секрета​

Полностью удаляет секрет из системы. Это действие необратимо.

  • Эндпоинт: DELETE /v1/secrets/{secret_id}
  • Параметры пути:
    • secret_id: Уникальный идентификатор секрета.
  • Ответ: 204 No Content

3. Управление связями секрета и проверки​

Получение всех секретов для проверки​

Возвращает список всех секретов, которые привязаны к конкретной проверке.

  • Эндпоинт: GET /v1/checks/{check_id}/secrets
  • Параметры пути:
    • check_id: Уникальный идентификатор проверки.
  • Ответ: 200 OK 
    [
      {
        "id": "cs123abc456",
        "secret_id": "sec123abc456",
        "env_variable": "PINGERA_API_TOKEN",
        "created_at": "2024-01-15T10:00:00Z"
      }
    ]

Добавление секрета к проверке​

Привязывает существующий секрет к конкретной проверке, делая его доступным через указанную переменную окружения.

  • Эндпоинт: POST /v1/checks/{check_id}/secrets
  • Параметры пути:
    • check_id: Уникальный идентификатор проверки.
  • Тело запроса: 
    {
      "secret_id": "sec123abc456",
      "env_variable": "PINGERA_API_TOKEN"
    }
  • Ответ: 201 Created 
    {
      "id": "cs123abc456",
      "secret_id": "sec123abc456",
      "env_variable": "PINGERA_API_TOKEN",
      "created_at": "2024-01-15T10:00:00Z"
    }

Обновление всех секретов для проверки​

Полностью заменяет все существующие связи секрета с проверкой на новые.

  • Эндпоинт: PUT /v1/checks/{check_id}/secrets
  • Параметры пути:
    • check_id: Уникальный идентификатор проверки.
  • Тело запроса: 
    [
      {
        "secret_id": "sec123abc456",
        "env_variable": "PINGERA_API_TOKEN"
      },
      {
        "secret_id": "sec456def789",
        "env_variable": "ANOTHER_SECRET"
      }
    ]
  • Ответ: 200 OK

Удаление секрета из проверки​

Удаляет связь между секретом и проверкой. Сам секрет остается в системе.

  • Эндпоинт: DELETE /v1/checks/{check_id}/secrets/{secret_id}
  • Параметры пути:
    • check_id: Уникальный идентификатор проверки.
    • secret_id: Уникальный идентификатор секрета.
  • Ответ: 204 No Content