Siirry sisältöön
Sursa Developers

POST/v1/api-keys

Luo API-avain

create_api_key

Todennus

Lähetä API-avain Authorization-otsakkeessa: Authorization: Bearer <avain>.

Otsakeparametrit

  • Idempotency-Keystring

    Avain kirjoituksen turvalliseen uusintayritykseen: 1–255 tulostettavaa ASCII-merkkiä; suositus on yksi UUID v4 jokaista loogista toimintoa kohden. Uusintayritys samalla avaimella 24 tunnin kuluessa ei suorita toimintoa uudelleen: se palauttaa tallennetun vastauksen (tila, otsakkeet ja runko) Idempotency-Replayed: true -otsakkeella. Sama avain eri metodilla, polulla, Content-Type-arvolla tai rungolla palauttaa 409 api.idempotency_mismatch; kun ensimmäinen pyyntö on vielä käynnissä, vastaus on 409 api.idempotency_in_progress ja Retry-After: 1. 5xx- tai 429-vastauksen jälkeen avain vapautuu, ja uusintayritys suorittaa toiminnon uudelleen. Avain on sidottu organisaatioon ja kutsujaan (API-avain, käyttäjä tai mukautetun lähteen avain).

    length ≥ 1, length ≤ 255

  • X-View-Asstring

    Vain API-avaimille, joilla on admin-rooli. Suorittaa pyynnön dataprofiilin <profile>[:viewer|verifier|editor] puolesta, esimerkiksi employee:viewer. Asennusavain ei voi käyttää tätä otsaketta (403).

Evästeparametrit

  • kb_view_asstring

    Istunnon ”View as” -tilan eväste. POST /auth/view-as asettaa sen ja DELETE /auth/view-as poistaa sen.

Pyynnön runko

application/json

Objekti: ApiKeyCreate

  • namestringpakollinen

    length ≥ 1, length ≤ 64

  • rolestring

    Oletus: "editor"

  • data_profilestring | null

    Avaimen dataprofiili. Ilman tätä kenttää avain saa organisaation oletusprofiilin. Dataprofiili ei koske admin-roolia. Avain, jolla on tämä rooli, näkee kaikki organisaation tiedot, ja muu profiili kuin full palauttaa 400 api_keys.data_profile_not_applicable.

  • expires_atstring (date-time) | null

    Avaimen vanhenemisaika (ISO 8601, tulevaisuudessa). null tai puuttuva arvo tarkoittaa, että avain ei vanhene.

  • scopesarray of ApiKeyScope | null

    Avaimen käyttöalueet. Jos kenttää ei ole, käyttöalueet määräytyvät roolin mukaan: admin saa käyttöalueet read, write, admin; editor ja verifier saavat read, write; viewer saa read. Käyttöalueen system myöntää vain asennuksen ylläpitäjä. Myös hienojakoiset resource:action-käyttöalueet (ApiKeyScope) hyväksytään; aiemmat read, write ja admin laajenevat käyttöalueiden joukoiksi.

  • collection_idsarray of integer | null

    Rajaa avaimen näihin organisaation kokoelmiin. Kortit, haku, vastaukset ja tapahtumat toimivat vain niissä; rajaus tulee roolin ja dataprofiilin lisäksi. Puuttuva arvo tai tyhjä luettelo tarkoittaa, ettei rajausta ole. Jos kutsuva avain on itse rajattu kokoelmiin, uusi avain voi olla vain sen kokoelmissa. Ilman tätä kenttää uusi avain saa kutsuvan avaimen kokoelmat. Tyhjä luettelo tai kokoelma sen luettelon ulkopuolelta palauttaa 400 api_keys.invalid_collections.

    items ≤ 100

  • allowed_cidrsarray of string | null

    Verkot, joista avainta voi käyttää, kuten 10.0.0.0/8 tai 2001:db8::/32. Yksittäinen osoite on yhden osoitteen verkko. Pyyntö muusta osoitteesta palauttaa 403 api_keys.ip_not_allowed. Puuttuva arvo tarkoittaa, ettei rajausta ole.

    items ≤ 50

Vastaukset

200Onnistunut vastaus

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

  • Idempotency-Replayed

    true tarkoittaa, että vastaus toistettiin tälle Idempotency-Key-arvolle tallennetusta vastauksesta: toimintoa ei suoritettu uudelleen.

application/json

Objekti: ApiKeyCreated

  • idintegerpakollinen
  • namestringpakollinen
  • prefixstringpakollinen
  • roleRolepakollinen
  • created_atstring (date-time)pakollinen
  • keystringpakollinen
  • data_profilestring | nullpakollinen
  • expires_atstring (date-time)

    Vanhenemisaika. Mukana vain avaimilla, joilla on vanhenemisaika.

  • scopesarray of string

    Avaimen erikseen määritetyt käyttöalueet. Mukana vain avaimilla, joille käyttöalueet on määritetty erikseen.

  • collection_idsarray of integer

    Kokoelmarajaus. Mukana vain avaimilla, joilla on rajaus.

  • allowed_cidrsarray of string

    Sallitut verkot. Mukana vain avaimilla, joilla on rajaus.

400Pyyntö on virheellinen: parametrin arvo tai objektin tila ei salli toimenpidettä (`detail` on viesti).

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

401Tunnistetietoja ei lähetetty (ei istuntoevästettä eikä API-avainta), tai avainta ei löytynyt.

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

403Toimenpide ei ole sallittu: rooli ei riitä, kokoelmaan tai korttiin ei ole käyttöoikeutta, pyyntö suoritetaan ”View as” -tilassa, tai organisaation toiminta on keskeytetty tai organisaatio on poistettu (`detail` on objekti, jossa on `code: org_suspended | org_deleted`).

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

422Validointivirhe: runko tai parametrit eivät vastaa skeemaa (`detail` on validointivirheiden lista), tai parametrin arvo on sallitun alueen ulkopuolella (`detail` on viesti).

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

429Liian monta pyyntöä (`api.rate_limited`), organisaation minuutti-, päivä- tai kuukausikiintiö on käytetty (`api.quota_exceeded`; `error.details` sisältää kentät `quota`, `limit` ja `reset_at`), organisaation raja on saavutettu tai vastauspalvelu on kuormitettu (`answers.engine_busy`). Odota `Retry-After`-otsakkeen ilmoittama aika.

Vastausotsakkeet

  • Retry-After

    Kuinka monta sekuntia odotetaan ennen pyynnön uusintayritystä.

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

Virhekoodit

Koodit, jotka tämä päätepiste voi palauttaa error.code-kentässä kaikkien pyyntöjen yleisten koodien lisäksi.

Turvalliset uusintayritykset

Lähetä jokaisen POST- ja PATCH-pyynnön mukana Idempotency-Key-otsake (esimerkiksi UUID). Kun pyyntö toistetaan samalla avaimella 24 tunnin kuluessa, palautetaan tallennettu vastaus eikä pyyntöä suoriteta uudelleen.

Nopeusrajoitukset

Vastauksissa ovat RateLimit- ja RateLimit-Policy-otsakkeet sekä aiemmat X-RateLimit-Limit, X-RateLimit-Remaining ja X-RateLimit-Reset. 429-vastauksessa on Retry-After sekunteina: odota ja yritä uudelleen.

← api-keys · API-viite