POST/v1/apps

Sukurti OAuth programą

create_app

Užregistruoja organizacijos programą. public – klientas be paslapties (naršyklė, mobilioji programa, CLI): tik autorizacijos kodas su PKCE. confidential – klientas su serveriu: gauna paslaptį ir taip pat kliento prisijungimo duomenis organizacijos vardu, su vaidmeniu role ir duomenų profiliu data_profile. Kliento paslaptis client_secret grąžinama tik šiame atsake ir rotacijos metu, todėl ją išsaugokite. Organizacija gali turėti iki 50 programų. Reikia leidimo ORG_MANAGE_KEYS; API raktui ar žetonui reikia apimties admin. Pridėta 1.62.0 versijoje.

Autentifikavimas

Siųskite API raktą antraštėje Authorization: Authorization: Bearer <raktas>.

Antraštės parametrai

Idempotency-Keystring
Raktas saugiam rašymo operacijos pakartojimui: nuo 1 iki 255 spausdinamų ASCII simbolių; rekomenduojamas atskiras UUID v4 kiekvienai loginei operacijai. Pakartojus užklausą su tuo pačiu raktu per 24 valandas, operacija iš naujo nevykdoma: grąžinamas išsaugotas atsakas (būsena, antraštės ir turinys) su antrašte Idempotency-Replayed: true. Tas pats raktas su kitu metodu, keliu, Content-Type ar turiniu grąžina 409 api.idempotency_mismatch; kol pirmoji užklausa dar vykdoma – 409 api.idempotency_in_progress su Retry-After: 1. Po 5xx ar 429 atsako raktas atlaisvinamas, ir pakartojimas operaciją vykdo iš naujo. Raktas galioja organizacijos ir iškvietėjo (API rakto, naudotojo arba pasirinktinio šaltinio rakto) ribose.
length ≥ 1, length ≤ 255

Užklausos turinys

application/json

Objektas: OAuthAppCreate

namestringprivalomas
Pavadinimas sutikimo langui.
length ≥ 1, length ≤ 100
descriptionstring
Aprašymas sutikimo langui.
length ≤ 1000
homepage_urlstring
Programos svetainė (http arba https).
length ≤ 2000
client_typeOAuthClientTypeprivalomas
redirect_urisarray of string
Peradresavimo URI: https; http – tik localhost, 127.0.0.1 ir [::1]; pasirinktinė programos schema – tik atvirkštinio domeno forma (com.example.app:/callback). Be fragmento. Viešajai programai reikia bent vieno URI.
items ≤ 10
scopesarray of OAuthScopeprivalomas
Apimtys, kurių programa gali prašyti.
items ≥ 1
rolestring
confidential programos kliento prisijungimo duomenų (client credentials) žetonų vaidmuo: admin, editor, verifier arba viewer (numatytasis – viewer).
data_profilestring
Kliento prisijungimo duomenų (client credentials) žetonų duomenų profilis; numatytasis – tas pats profilis, kaip naujam API raktui.

Atsakai

201Programa sukurta.

Atsako antraštės

RateLimit-Policy
Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.
RateLimit
Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.
X-RateLimit-Remaining
Likusių užklausų skaičius pagal griežčiausią limitą.
X-RateLimit-Reset
Sekundės iki griežčiausio limito atsistatymo.
Idempotency-Replayed
true – atsakas pakartotas iš šiam Idempotency-Key išsaugoto atsako: operacija iš naujo nevykdyta.

application/json

Objektas: OAuthAppWithSecret

idstringprivalomas
Programos ID (app_ ir 32 šešioliktainiai simboliai), kuris kartu yra ir client_id.
namestringprivalomas
Pavadinimas, kurį darbuotojas mato sutikimo lange.
descriptionstringprivalomas
Aprašymas sutikimo langui (gali būti tuščias).
homepage_urlstring | nullprivalomas
Programos svetainė.
client_typeOAuthClientTypeprivalomas
redirect_urisarray of stringprivalomas
Leidžiami peradresavimo URI (tikslus eilutės atitikimas).
scopesarray of OAuthScopeprivalomas
Apimtys, kurių programa gali prašyti.
client_secret_prefixstring | nullprivalomas
Pirmieji kliento paslapties simboliai, kad ją būtų galima atpažinti; viešajai programai – null.
rolestring | nullprivalomas
Kliento prisijungimo duomenų (client credentials) žetonų vaidmuo (admin, editor, verifier, viewer); viešajai programai – null.
data_profilestring | nullprivalomas
Kliento prisijungimo duomenų (client credentials) žetonų duomenų profilis; viešajai programai – null.
authorizationsintegerprivalomas
Aktyvių darbuotojų autorizacijų skaičius.
created_atstring (date-time)privalomas
updated_atstring (date-time)privalomas
client_secretstring | nullprivalomas
Kliento paslaptis (kbcs_…), rodoma vieną kartą; viešajai programai – null.

400Užklausa netinkama: parametro reikšmė arba objekto būsena neleidžia atlikti veiksmo (`detail` – pranešimas).

Atsako antraštės

RateLimit-Policy
Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.
RateLimit
Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.
X-RateLimit-Remaining
Likusių užklausų skaičius pagal griežčiausią limitą.
X-RateLimit-Reset
Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

401Prisijungimo duomenys neišsiųsti (nei sesijos slapukas, nei API raktas) arba raktas nerastas.

Atsako antraštės

RateLimit-Policy
Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.
RateLimit
Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.
X-RateLimit-Remaining
Likusių užklausų skaičius pagal griežčiausią limitą.
X-RateLimit-Reset
Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

403Veiksmas neleidžiamas: vaidmuo nesuteikia reikiamų teisių, nėra prieigos prie rinkinio ar kortelės, užklausa vykdoma režimu „View as“ arba organizacijos veikla sustabdyta ar organizacija ištrinta (`detail` – objektas su `code: org_suspended | org_deleted`).

Atsako antraštės

RateLimit-Policy
Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.
RateLimit
Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.
X-RateLimit-Remaining
Likusių užklausų skaičius pagal griežčiausią limitą.
X-RateLimit-Reset
Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

409Objekto būsena neleidžia atlikti veiksmo, pvz., dublikatas, vyksta indeksavimas arba darbas jau apdorotas.

Atsako antraštės

RateLimit-Policy
Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.
RateLimit
Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.
X-RateLimit-Remaining
Likusių užklausų skaičius pagal griežčiausią limitą.
X-RateLimit-Reset
Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

422Validavimo klaida: turinys ar parametrai neatitinka schemos (`detail` – validavimo klaidų sąrašas) arba parametro reikšmė nepatenka į leistiną intervalą (`detail` – pranešimas).

Atsako antraštės

RateLimit-Policy
Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.
RateLimit
Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.
X-RateLimit-Remaining
Likusių užklausų skaičius pagal griežčiausią limitą.
X-RateLimit-Reset
Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

429Per daug užklausų (`api.rate_limited`), išnaudota organizacijos minutės, dienos ar mėnesio kvota (`api.quota_exceeded`; `error.details` pateikia `quota`, `limit` ir `reset_at`), pasiektas organizacijos limitas arba atsakymų paslauga užimta (`answers.engine_busy`). Palaukite tiek, kiek nurodyta antraštėje `Retry-After`.

Atsako antraštės

Retry-After
Kiek sekundžių palaukti prieš kartojant užklausą.
RateLimit-Policy
Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.
RateLimit
Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.
X-RateLimit-Remaining
Likusių užklausų skaičius pagal griežčiausią limitą.
X-RateLimit-Reset
Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

Klaidų kodai

Kodai, kuriuos ši operacija gali grąžinti lauke error.code, be bendrųjų kodų, galimų bet kuriai užklausai.

Saugūs pakartojimai

Su kiekviena POST ir PATCH užklausa siųskite antraštę Idempotency-Key (pavyzdžiui, UUID). Pakartojus užklausą su tuo pačiu raktu per 24 valandas, grąžinamas išsaugotas atsakas, o užklausa iš naujo nevykdoma.

Užklausų dažnio limitai

Atsakuose yra antraštės RateLimit ir RateLimit-Policy bei ankstesnės X-RateLimit-Limit, X-RateLimit-Remaining ir X-RateLimit-Reset. Atsake 429 yra antraštė Retry-After sekundėmis: palaukite ir pakartokite užklausą.

← apps · API žinynas

curl -X POST 'https://api.sursa.com/v1/apps' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"support","client_type":"public","scopes":["cards:read"]}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Išbandyti

API raktas

Raktas laikomas tik šio skirtuko atmintyje ir siunčiamas tik į https://api.sursa.com.

Užklausos vykdomos su tikrais jūsų organizacijos duomenimis.

Idempotency-Key header

Idempotency-Key

Jei laukas tuščias, kiekvienai užklausai sugeneruojamas naujas raktas.

Užklausos turinys (JSON)