Izstrādātājiem & AI

Vairogs API & MCP

Piekļūstiet sava seifa saturam programmatiski ar zero-knowledge šifrēšanu.

API v1 (Read-Only)

tikai lasīšana

Lasīšanas piekļuve pilnai šifrētajai seifa satura versijai. Atšifrēšanai nepieciešama lietotāja galvenā parole.

Pārskats

API v1 nodrošina tikai lasīšanas piekļuvi visam šifrētajam seifam. Atšķirībā no Tag API v2, šis API atgriež neapstrādātus šifrētus datus, kuriem nepieciešama lietotāja galvenā parole atšifrēšanai.

Tikai lasīšana

Pieejami tikai GET pieprasījumi. Nav iespējams izveidot, atjaunināt vai dzēst ierakstus.

Pilna piekļuve seifam

Piekļūst visiem lietotāja ierakstiem bez tag ierobežojumiem.

Nepieciešama galvenā parole

Datu atšifrēšanai klientam jāzina lietotāja galvenā parole.

Zero-knowledge

Serveris neatšifrē datus - visa atšifrēšana notiek klienta pusē.

ĪpašībaAPI v1 (vglv_)Tag API v2 (vgtk_)
PiekļuvePilns seifsTikai ar tagiem iezīmēti
RakstīšanaJā (CRUD)
AtšifrēšanaNepieciešama galvenā paroleAPI atslēga atvasina atslēgu pāri
LietojumsRezerves kopijas, eksportēšanaMCP/AI integrācija

Svarīgi

API v1 ir paredzēts rezerves kopiju un eksportēšanas rīkiem. Automatizētai piekļuvei bez galvenās paroles izmantojiet Tag API v2, kas nodrošina droša atslēgu pāra šifrēšanu bez nepieciešamības zināt galveno paroli.

Autentifikācija

Visi pieprasījumi prasa API atslēgu X-API-Key galvenē.

http
X-API-Key: vglv_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

API atslēgas izmanto vglv_ prefiksu (32 alfanumeriski simboli pēc prefiksa).

API Atslēgas Izveide

1

Atveriet Iestatījumus

Dodieties uz Iestatījumi > API Pieejas savā seifā

2

Izveidojiet atslēgu

Noklikšķiniet "Izveidot API Atslēgu" un ievadiet aprakstu

3

Saglabājiet drošā vietā

Atslēga tiek rādīta tikai vienu reizi! Saglabājiet to vides mainīgajā vai secrets manager.

Ātruma ierobežojumi

FREE: 60 pieprasījumi/minūte
PRO: 600 pieprasījumi/minūte

API Galapunkti

Visi pieejamie lasīšanas galapunkti.

GET/api/v1/items

Saraksts ar visiem šifrētajiem ierakstiem ar pagināciju.

Query Parametri

ParametrsTipsApraksts
typestringFiltrēt pēc tipa: PASSWORD, NOTE, IMAGE, DOCUMENT, TOTP
limitnumberRezultātu skaits uz lapu (maksimums: 500, noklusējums: 100)
offsetnumberPaginācijas nobīde (noklusējums: 0)

Piemērs

bash
curl https://vairogs.lv/api/v1/items \
  -H "X-API-Key: vglv_YOUR_KEY_HERE"

curl "https://vairogs.lv/api/v1/items?type=PASSWORD&limit=50" \
  -H "X-API-Key: vglv_YOUR_KEY_HERE"

Atbilde

json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "type": "PASSWORD",
        "title": "GitHub",
        "encryptedData": "base64...",
        "iv": "base64...",
        "labels": ["tag_id_1"],
        "createdAt": "2025-01-01T00:00:00.000Z",
        "updatedAt": "2025-01-01T00:00:00.000Z"
      }
    ],
    "salt": "base64...",
    "pagination": {
      "total": 42,
      "limit": 100,
      "offset": 0,
      "hasMore": false
    },
    "encryption": {
      "algorithm": "AES-256-GCM",
      "keyDerivation": "PBKDF2",
      "iterations": 100000
    }
  }
}
GET/api/v1/items/:id

Iegūstiet vienu šifrētu ierakstu pēc ID.

Piemērs

bash
curl https://vairogs.lv/api/v1/items/ITEM_ID \
  -H "X-API-Key: vglv_YOUR_KEY_HERE"

Atbilde

json
{
  "success": true,
  "data": {
    "item": {
      "id": "uuid",
      "type": "PASSWORD",
      "title": "GitHub",
      "encryptedData": "base64...",
      "iv": "base64...",
      "labels": ["tag_id_1"],
      "createdAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-01-01T00:00:00.000Z"
    },
    "salt": "base64...",
    "encryption": {
      "algorithm": "AES-256-GCM",
      "keyDerivation": "PBKDF2",
      "iterations": 100000
    }
  }
}

Atšifrēšana Klienta Pusē

Kā atšifrēt API v1 atgrieztos datus ar lietotāja galveno paroli.

API v1 atgriež datus, kas šifrēti ar lietotāja galveno paroli. Atšifrēšanai:

1

Atvasināt šifrēšanas atslēgu

Izmantojiet PBKDF2 ar galveno paroli un salt no API atbildes

2

Atšifrēt datus

Izmantojiet AES-256-GCM ar atvasināto atslēgu un IV no ieraksta

3

Parsēt JSON

Atšifrētie dati ir JSON formātā ar ieraksta laukiem

1. Atslēgas Atvasināšana

javascript
const { pbkdf2Sync } = require('crypto');

const masterPassword = 'lietotāja_galvenā_parole';
const salt = response.salt; // base64 no API

// Atvasināt 256-bitu atslēgu ar PBKDF2
const key = pbkdf2Sync(
  masterPassword,
  Buffer.from(salt, 'base64'),
  100000,  // iterācijas
  32,      // 256 biti
  'sha256'
);

2. Datu Atšifrēšana

javascript
const crypto = require('crypto');

function decryptItem(encryptedData, iv, key) {
  const decipher = crypto.createDecipheriv(
    'aes-256-gcm',
    key,
    Buffer.from(iv, 'base64')
  );

  const encrypted = Buffer.from(encryptedData, 'base64');

  // Pēdējie 16 baiti ir autentifikācijas tags
  const authTag = encrypted.slice(-16);
  const ciphertext = encrypted.slice(0, -16);

  decipher.setAuthTag(authTag);

  const decrypted = Buffer.concat([
    decipher.update(ciphertext),
    decipher.final()
  ]);

  return JSON.parse(decrypted.toString('utf8'));
}

// Lietojums
const item = response.items[0];
const plaintext = decryptItem(item.encryptedData, item.iv, key);
console.log(plaintext);
// { username: '...', password: '...', url: '...', notes: '...' }

Pilns Piemērs (Node.js)

javascript
const { pbkdf2Sync, createDecipheriv } = require('crypto');

const API_KEY = process.env.VAIROGS_API_KEY;
const MASTER_PASSWORD = process.env.VAIROGS_MASTER_PASSWORD;
const BASE_URL = 'https://vairogs.lv/api/v1';

async function fetchAndDecrypt() {
  // 1. Iegūt ierakstus
  const response = await fetch(`${BASE_URL}/items`, {
    headers: { 'X-API-Key': API_KEY }
  });
  const { data } = await response.json();

  // 2. Atvasināt šifrēšanas atslēgu
  const key = pbkdf2Sync(
    MASTER_PASSWORD,
    Buffer.from(data.salt, 'base64'),
    100000,
    32,
    'sha256'
  );

  // 3. Atšifrēt katru ierakstu
  const decryptedItems = data.items.map(item => {
    try {
      const encrypted = Buffer.from(item.encryptedData, 'base64');
      const iv = Buffer.from(item.iv, 'base64');
      const authTag = encrypted.slice(-16);
      const ciphertext = encrypted.slice(0, -16);

      const decipher = createDecipheriv('aes-256-gcm', key, iv);
      decipher.setAuthTag(authTag);

      const decrypted = Buffer.concat([
        decipher.update(ciphertext),
        decipher.final()
      ]);

      return {
        id: item.id,
        type: item.type,
        title: item.title,
        data: JSON.parse(decrypted.toString())
      };
    } catch (error) {
      return { id: item.id, error: 'Atšifrēšana neizdevās' };
    }
  });

  return decryptedItems;
}

fetchAndDecrypt().then(items => {
  console.log('Atšifrētie ieraksti:', items);
});

Ierobežojumi & Drošība

Svarīgi apsvērumi, izmantojot API v1.

Galvenās Paroles Risks

API v1 prasa galveno paroli atšifrēšanai. Ja parole tiek kompromitēta, viss seifa saturs ir pieejams. Apsvēriet Tag API v2 automatizētai piekļuvei.

Pilna Seifa Piekļuve

API v1 piešķir piekļuvi VISIEM ierakstiem bez tag ierobežojumiem. Izmantojiet Tag API v2, lai ierobežotu piekļuvi tikai noteiktiem ierakstiem.

HTTPS Obligāts

Vienmēr izmantojiet HTTPS produkcijā. Nekad nesūtiet API atslēgas vai galvenās paroles pa nedrošiem savienojumiem.

Atslēgu Uzglabāšana

Glabājiet API atslēgas vides mainīgajos vai secrets manager. Nekad neievietojiet tās koda repozitorijā. Regulāri rotējiet atslēgas.

Kad Izmantot API v1 vs Tag API v2

Lietojuma GadījumsIeteicamais API
Rezerves kopijas / eksportēšanas rīkiAPI v1
MCP / AI integrācijaTag API v2
Automatizēti skripti ar galveno paroliAPI v1
Skripti bez galvenās parolesTag API v2
Pilna seifa piekļuve nepieciešamaAPI v1
Ierobežota / tag-based piekļuveTag API v2

Ieteikums

Lielākajai daļai moderno integrāciju, īpaši MCP un AI asistentiem, ieteicams izmantot Tag API v2. Tas nodrošina labāku drošību ar scoped piekļuvi un neatkarīgiem šifrēšanas atslēgu pāriem bez nepieciešamības zināt galveno paroli.

Kļūdu Kodi

API v1 atgrieztie kļūdu kodi un to nozīmes.

CodeHTTP StatusDescription
API_KEY_REQUIRED401Trūkst X-API-Key galvenes
INVALID_API_KEY401Nederīga vai neaktīva API atslēga
VAULT_NOT_FOUND404Šim lietotājam neeksistē seifs
VAULT_PARSE_ERROR500Neizdevās parsēt seifa datus
RATE_LIMIT_EXCEEDED429Pārsniegts ātruma ierobežojums
INTERNAL_ERROR500Servera kļūda