Pamācības

Autentifikācija

Katrs pieprasījums tiek autentificēts ar piekļuves datiem, ko izsniedza BoxLatvia. Vienkāršākajai integrācijai izmantojiet HTTP Basic vai OAuth 2.0, ja to sagaida jūsu rīki. Abi nodrošina vienādu piekļuvi.

#HTTP Basic

Katrā pieprasījumā nosūtiet client ID kā lietotājvārdu un noslēpumu kā paroli. Gandrīz katra HTTP bibliotēka to izdara jūsu vietā.

curl "$API/v1/me" \
  -u "$CLIENT_ID:$CLIENT_SECRET"

const API = "https://api.boxlatvia.lv";
const auth = "Basic " + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`);

const res = await fetch(`${API}/v1/me`, {
  headers: { Authorization: auth },
});
console.log(res.status, await res.json());

import requests

API = "https://api.boxlatvia.lv"
r = requests.get(
    f"{API}/v1/me",
    auth=(CLIENT_ID, CLIENT_SECRET),
)
print(r.status_code, r.json())

Vienmēr izmantojiet HTTPS. API nekad nepieņem piekļuves datus, kas sūtīti pa parasto HTTP.

#OAuth 2.0 client credentials

Apmainiet savus piekļuves datus pret īslaicīgu bearer token un sūtiet to. Tokeni derīgi 15 minūtes: kad API atbild ar 401, pieprasiet jaunu. Saglabājiet tokenu un atjaunojiet to minūti pirms beigām, nevis pieprasiet jaunu katram izsaukumam.

#Iegūt piekļuves token

POST/v1/oauth/tokentiesības nav vajadzīgas

OAuth 2.0 client credentials: apmainiet savu client id un noslēpumu pret bearer token, kas derīgs 15 minūtes.

Nosūtiet piekļuves datus kā HTTP Basic (kā piemērā) vai kā client_id un client_secret formas saturā. Kļūdas atbilst OAuth standartam (invalid_client, invalid_scope, …), nevis parastajam kļūdu formātam.

Pieprasījuma saturs (application/x-www-form-urlencoded)

Nosaukums	Tips	Apraksts
`grant_type` obligāts	string	Vienmēr `client_credentials`.
`scope`	string	Ar atstarpēm atdalītas tiesības, kādas vēlaties tokenam. Noklusējums: viss, ko atļauj jūsu piekļuves dati. Vairāk pieprasīt nevar.

Piemēri

Token pieprasīšana

curl -X POST "$API/v1/oauth/token" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d "scope=boxes:read boxes:write"

const API = "https://api.boxlatvia.lv";
const auth = "Basic " + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`);

const res = await fetch(`${API}/v1/oauth/token`, {
  method: "POST",
  headers: { Authorization: auth },
  body: new URLSearchParams({
    "grant_type": "client_credentials",
    "scope": "boxes:read boxes:write"
  }),
});
console.log(res.status, await res.json());

import requests

API = "https://api.boxlatvia.lv"
r = requests.post(
    f"{API}/v1/oauth/token",
    auth=(CLIENT_ID, CLIENT_SECRET),
    data={
        "grant_type": "client_credentials",
        "scope": "boxes:read boxes:write",
    },
)
print(r.status_code, r.json())

200 OK

{
  "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FwaS5ib3hsYXR2aWEubHYi…",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "boxes:read boxes:write"
}

Nepareizi piekļuves dati

curl -X POST "$API/v1/oauth/token" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials

const API = "https://api.boxlatvia.lv";
const auth = "Basic " + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`);

const res = await fetch(`${API}/v1/oauth/token`, {
  method: "POST",
  headers: { Authorization: auth },
  body: new URLSearchParams({
    "grant_type": "client_credentials"
  }),
});
console.log(res.status, await res.json());

import requests

API = "https://api.boxlatvia.lv"
r = requests.post(
    f"{API}/v1/oauth/token",
    auth=(CLIENT_ID, CLIENT_SECRET),
    data={
        "grant_type": "client_credentials",
    },
)
print(r.status_code, r.json())

401 Unauthorized

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials."
}

Kļūdas

Statuss	Kad
400	`invalid_request`, `unsupported_grant_type` vai `invalid_scope`.
401	`invalid_client`: id vai noslēpums ir nepareizs, vai piekļuve ir atsaukta vai beigusies.
429	Pārāk daudz neveiksmīgu mēģinājumu no jūsu adreses.

#Token lietošana

curl "$API/v1/me" \
  -H "Authorization: Bearer $TOKEN"

Tokenam ir tikai tās tiesības, ko pieprasījāt. Piekļuves datu atsaukšana vai to tiesību sašaurināšana stājas spēkā jau nākamajā pieprasījumā, arī jau izsniegtiem tokeniem. Parakstīšanas atslēgas ir publicētas /v1/.well-known/jwks.json.

#Tiesības (scopes)

Tiesības nosaka, ko piekļuves datu komplekts drīkst darīt. Pieprasiet tikai to, kas integrācijai nepieciešams.

Tiesības	Atļauj
`reference:read`	Lasīt atsauces sarakstus (ērtības, rajoni, cenas mērvienības, izmēri).
`supplier:read`	Lasīt jūsu piegādātāja profilu un `GET /v1/me`.
`supplier:write`	Mainīt profila kontaktinformācijas un adreses laukus.
`locations:read`	Iegūt lokāciju sarakstu un lokācijas, kā arī to attēlus.
`locations:write`	Izveidot, mainīt un dzēst lokācijas.
`boxes:read`	Iegūt telpu sarakstu un telpas, kā arī to attēlus.
`boxes:write`	Izveidot, mainīt un dzēst telpas; iesniegt un atsaukt tās.
`images:write`	Augšupielādēt un dzēst telpu un lokāciju attēlus.

Izsaukums bez vajadzīgajām tiesībām tiek atbildēts ar 403, un trūkstošās tiesības ir norādītas required_scope.

Trūkstošas tiesības

curl -X POST "$API/v1/boxes" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Box",
  "location_id": "9d80d5f4-d17a-4f3e-99f6-4ab43b132bc3"
}'

const API = "https://api.boxlatvia.lv";
const auth = "Basic " + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`);

const res = await fetch(`${API}/v1/boxes`, {
  method: "POST",
  headers: { Authorization: auth, "Content-Type": "application/json" },
  body: JSON.stringify({
    "name": "Box",
    "location_id": "9d80d5f4-d17a-4f3e-99f6-4ab43b132bc3"
  }),
});
console.log(res.status, await res.json());

import requests

API = "https://api.boxlatvia.lv"
r = requests.post(
    f"{API}/v1/boxes",
    auth=(CLIENT_ID, CLIENT_SECRET),
    json={
        "name": "Box",
        "location_id": "9d80d5f4-d17a-4f3e-99f6-4ab43b132bc3",
    },
)
print(r.status_code, r.json())

403 Forbidden

{
  "type": "https://api.boxlatvia.lv/problems/insufficient-scope",
  "title": "Forbidden",
  "status": 403,
  "detail": "This operation needs the scope boxes:write.",
  "request_id": "d504c7e6-8458-456a-884d-0b4ba02be2d3",
  "required_scope": "boxes:write"
}

#Piekļuves datu ierobežojumi

Atļauto IP adrešu saraksts. Ja BoxLatvia to jums iestata, izsaukumi no jebkuras citas adreses tiek atteikti ar 403.
Derīguma termiņš. Piekļuves datiem var būt beigu datums, pēc kura tie pārstāj darboties.
Atsaukšana un nomaiņa. BoxLatvia jebkurā brīdī var atsaukt piekļuves datus vai izsniegt jaunu noslēpumu; vecais noslēpums uzreiz pārstāj darboties. Nekavējoties pastāstiet mums, ja noslēpums varētu būt kļuvis zināms citiem.

#Neveiksmīgi pieteikšanās mēģinājumi

Pēc 10 neveiksmīgām autentifikācijām 5 minūšu laikā no vienas IP adreses turpmākie izsaukumi no šīs adreses tiek atbildēti ar 429 un galveni Retry-After (sekundēs), līdz laika logs paiet. Neatkārtojiet 401 ciklā.

Bloķēts

curl "$API/v1/me" \
  -u "$CLIENT_ID:$CLIENT_SECRET"

const API = "https://api.boxlatvia.lv";
const auth = "Basic " + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`);

const res = await fetch(`${API}/v1/me`, {
  headers: { Authorization: auth },
});
console.log(res.status, await res.json());

import requests

API = "https://api.boxlatvia.lv"
r = requests.get(
    f"{API}/v1/me",
    auth=(CLIENT_ID, CLIENT_SECRET),
)
print(r.status_code, r.json())

429 Too Many RequestsRetry-After: 300

{
  "type": "https://api.boxlatvia.lv/problems/too-many-requests",
  "title": "Too many requests",
  "status": 429,
  "detail": "Too many failed authentication attempts. Try again later.",
  "request_id": "88b1f62d-3509-4d1f-b542-ff67a35787ae"
}

#Noslēpuma drošība

Glabājiet noslēpumu noslēpumu pārvaldniekā vai vides mainīgajā, nekad pirmkodā, priekšpuses kodā vai žurnālos.
Izmantojiet atsevišķus piekļuves datus katrai sistēmai un videi.
Izsauciet API tikai no savām serveriem, nekad no pārlūkprogrammas vai mobilās lietotnes.