Izstrādātājiem & AI

Vairogs API & MCP

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

Autentifikācija

API atslēgas, šifrēšanas režīmi un piekļuves ierobežojumi

Šifrēšanas Režīmi

Tag API v2 piedāvā divus atšķirīgus šifrēšanas režīmus. Izvēlieties atbilstošo atkarībā no jūsu drošības prasībām un integrācijas sarežģītības.

IETEICAMS

Zero-Knowledge

Maksimāla drošība

Divas atslēgas — serveris nekad neredz jūsu datus. Šifrēšana un atšifrēšana notiek tikai jūsu pusē.

Access Key (vgtk_a_xxx) — autentifikācijai
Decryption Key (vgtk_d_xxx) — atšifrēšanai
Šifrēšana klienta pusē (client-side)
MCP / Claude Desktop compatible

DROŠĪBAS LĪMENIS

ĒRTĀK

Server-Managed

Vienkāršāka integrācija

Viena atslēga — serveris atšifrē datus pieprasījuma brīdī. Vienkāršāk integrēt, bet mazāk drošs.

Viena API atslēga (vgtk_m_xxx)
Atšifrēšana serverī (server-side)
Atgriež atšifrētus datus tieši
Nav nepieciešama klienta kriptogrāfija

DROŠĪBAS LĪMENIS

AspektsZero-KnowledgeServer-Managed
Atslēgu skaits2 (access + decrypt)1 (managed)
Atšifrēšana notiekKlienta pusēServerī
Šifrēšana (rakstīšana)Klienta pusēServerī
Serveris redz datusNekadPieprasījuma laikā
Integrācijas sarežģītībaAugstākaZemāka
MCP / Claude Desktop✓ Pilnībā✓ Vienkāršots
Ieteicams priekšSensitīvi dati, complianceĀtra integrācija, prototipi

Drošības kompromiss

Server-Managed režīmā jūsu dati tiek atšifrēti mūsu serverī pieprasījuma apstrādes laikā. Lai gan mēs izmantojam TLS un drošu infrastruktūru, šis režīms nav zero-knowledge. Sensitīviem datiem vienmēr izvēlieties Zero-Knowledge režīmu.

API Atslēgu Iegūšana

PRO funkcija

API atslēgas var ģenerēt tikai autentificētie lietotāji ar PRO plānu. Atslēgas ir saistītas ar jūsu kontu un konkrētiem tagiem.
1

Ieejiet savā Vairogs seifā

Autentificējieties izmantojot jebkuru pieejamo metodi (Google, Draugiem.lv, eID, vai e-pasta OTP).

2

Atveriet iestatījumus

Augšējā labajā stūrī noklikšķiniet uz sava profila ikonas un izvēlieties "Iestatījumi".

3

Navigējiet uz Tag API sadaļu

Iestatījumu modalajā logā atrodiet "Tag API v2 Atslēgas" cilni.

4

Izvēlieties šifrēšanas režīmu

Izvēlieties starp "Zero-Knowledge" (2 atslēgas) vai "Server-Managed" (1 atslēga).

5

Konfigurējiet ierobežojumus

Iestatiet atļaujas, IP adreses un derīguma termiņu (skatīt sadaļu zemāk).

6

Ģenerējiet un saglabājiet

Noklikšķiniet "Izveidot" un nekavējoties saglabājiet atslēgas drošā vietā. Tās vairs netiks rādītas!

Atslēgu Ierobežojumi

Katrai API atslēgai varat konfigurēt precīzus ierobežojumus, lai nodrošinātu minimālo nepieciešamo piekļuvi.

Atļaujas (Permissions)

Kontrolējiet, kādas darbības atslēga var veikt

vault:read

Lasīt seifa informāciju

items:read

Lasīt vienumu sarakstu un saturu

items:write

Izveidot un rediģēt vienumus

files:read

Lejupielādēt failus un attēlus

files:write

Augšupielādēt jaunus failus

items:delete

Dzēst vienumus (neatgriezeniski)

Minimālo tiesību princips

Piešķiriet tikai nepieciešamās atļaujas. Piemēram, ja jūsu integrācija tikai lasa datus, neieslēdziet items:write vai items:delete.

IP Baltais Saraksts (IP Whitelist)

Ierobežojiet piekļuvi tikai no konkrētām IP adresēm

Ja norādīts, API atslēga darbosies tikai no šīm IP adresēm vai tīkliem. Atstājiet tukšu, lai atļautu no jebkuras IP.

ATBALSTĪTIE FORMĀTI

192.168.1.100— Konkrēta IP adrese
10.0.0.0/24— CIDR notācija (256 adreses)
2001:db8::1— IPv6 adrese
text
# Piemērs: Pieļaut tikai no biroja un mākoņa serveriem
192.168.1.100
10.0.0.0/24
185.123.45.67
2001:db8::/32

Dinamiskās IP

Ja jūsu serverim ir dinamiska IP adrese (piemēram, mājas internets), IP baltais saraksts var izraisīt piekļuves problēmas. Šādos gadījumos labāk izmantojiet citus drošības mehānismus.

Derīguma Termiņš (Expiration)

Iestatiet, kad atslēga automātiski beigs darboties

Atslēgai var norādīt derīguma termiņu. Pēc šī datuma atslēga automātiski tiks deaktivēta.

Nekad

Atslēga darbojas bezgalīgi

30 dienas

Īstermiņa piekļuve

Konkrēts datums

Piemēram, 2025-12-31

Ieteikums

Īslaicīgām integrācijām, testēšanai vai trešo pušu piekļuvei vienmēr iestatiet derīguma termiņu. Tas nodrošina, ka aizmirstas atslēgas automātiski tiek deaktivētas.

Atslēgu Prefiksi

Katrai atslēgai ir unikāls prefikss, kas norāda tās tipu un mērķi:

vgtk_a_Access Key (Zero-Knowledge)

Autentifikācijas atslēga. Šo nosūtāt X-API-Key headerī. Neļauj atšifrēt datus.

vgtk_d_Decryption Key (Zero-Knowledge)

Atšifrēšanas atslēga. Glabāt tikai klienta pusē! Nekad nesūtīt serverim.

vgtk_m_Managed Key (Server-Managed)

Viena atslēga, kas ļauj gan autentificēties, gan saņemt atšifrētus datus no servera.

vglv_Legacy API v1 Key

Read-only piekļuve visam seifam. Atgriež šifrētus datus (nepieciešams master password).

HTTP Autentifikācija

Visiem API pieprasījumiem jāiekļauj X-API-Key header.

Zero-Knowledge režīms

http
GET /api/v2/tag/items HTTP/1.1
Host: vairogs.lv
X-API-Key: vgtk_a_xxxxxxxxxxxxxx
Content-Type: application/json

# Decryption Key glabājas lokāli
# un izmanto klienta pusē

Server-Managed režīms

http
GET /api/v2/tag/items HTTP/1.1
Host: vairogs.lv
X-API-Key: vgtk_m_xxxxxxxxxxxxxx
Content-Type: application/json

# Serveris automātiski atšifrē
# un atgriež skaidrus datus
ParametrsTipsApraksts
X-API-Key*stringAccess Key (vgtk_a_xxx), Managed Key (vgtk_m_xxx), vai Legacy Key (vglv_xxx)

Koda Piemēri

Zero-Knowledge režīms (ieteicams)

typescript
import { VairogsClient } from '@vairogs/sdk'

// Zero-Knowledge: divas atslēgas, klienta puses atšifrēšana
const client = new VairogsClient({
  accessKey: 'vgtk_a_xxxxxxxxxxxxxxxxxxxxxx',
  decryptionKey: 'vgtk_d_xxxxxxxxxxxxxxxxxxxxxx'  // Tikai lokāli!
})

// SDK automātiski atšifrē klienta pusē
const items = await client.getItems()
console.log(items)  // Atšifrēti dati

Server-Managed režīms (vienkāršāk)

typescript
// Server-Managed: viena atslēga, serveris atšifrē
const response = await fetch('https://vairogs.lv/api/v2/tag/items', {
  headers: {
    'X-API-Key': 'vgtk_m_xxxxxxxxxxxxxxxxxxxxxx'
  }
})

const { data } = await response.json()
console.log(data.items)  // Jau atšifrēti dati no servera!

// Nav nepieciešama klienta puses kriptogrāfija
// Dati tiek atšifrēti serverī pieprasījuma laikā

Python piemērs (Server-Managed)

python
import requests

# Server-Managed: vienkāršākā integrācija
headers = {
    'X-API-Key': 'vgtk_m_xxxxxxxxxxxxxxxxxxxxxx'
}

response = requests.get('https://vairogs.lv/api/v2/tag/items', headers=headers)
data = response.json()

# Dati jau atšifrēti!
for item in data['data']['items']:
    print(f"{item['title']}: {item['decryptedData']}")

Rate Limiting

API pieprasījumiem ir ierobežojumi, lai novērstu ļaunprātīgu izmantošanu:

FREE Tier

  • • Nav API piekļuves

PRO Tier

  • • 300 pieprasījumi / minūte
  • • 10,000 pieprasījumi / dienā
  • • Pilna Tag API v2 piekļuve

429 Too Many Requests

Ja pārsniedzat limitus, saņemsiet 429 atbildi ar Retry-After header.

Kļūdu Atbildes

401Unauthorized

API atslēga nav norādīta, ir nepareiza, vai ir deaktivēta/expired.

403Forbidden

Atslēgai nav nepieciešamās atļaujas šai darbībai, vai IP nav baltajā sarakstā.

429Too Many Requests

Pārsniegts rate limit. Gaidiet un mēģiniet vēlreiz.

Labākās Prakses

Izvēlieties pareizo režīmu

Sensitīviem datiem — Zero-Knowledge. Ātriem prototipiem — Server-Managed.

Ierobežojiet atļaujas

Piešķiriet tikai nepieciešamās atļaujas katrai atslēgai.

Izmantojiet IP whitelist

Ja iespējams, ierobežojiet piekļuvi tikai no zināmām IP adresēm.

Iestatiet derīguma termiņu

Īslaicīgām integrācijām vienmēr norādiet termiņu.

Rotējiet atslēgas regulāri

Izveidojiet jaunas atslēgas ik pēc dažiem mēnešiem.

Nekad necommitējiet atslēgas

Izmantojiet environment variables vai secret managers.