Todennus

API todentaa palvelimet organisaation API-avaimilla. Avain kuuluu organisaatiolle (ei henkilölle), sillä on joukko käyttöoikeuksia, ja se toimii täsmälleen yhdessä tilassa: testi tai tuotanto (live).

Avaimen lähettäminen

Käytä jompaakumpaa otsaketta:

# Authorization header (recommended)
curl https://api.bonafidesign.com/v1/envelopes -H "Authorization: Bearer bf_live_…"

# or x-api-key
curl https://api.bonafidesign.com/v1/envelopes -H "x-api-key: bf_live_…"

Avaimet näyttävät tältä: bf_live_… tai bf_test_…. Puuttuva avain on 401 (unauthorized); virheellisen muotoinen, peruutettu tai vanhentunut avain on myös 401. Pidä avaimet palvelimellasi: älä koskaan toimita niitä selaimeen tai mobiilisovellukseen. Selaimessa allekirjoittamista varten luo sen sijaan allekirjoitusistunto.

Testi- ja tuotantoavaimet

	Testi (`bf_test_…`)	Tuotanto (`bf_live_…`)
Asiakirjat	Renderöidään `TEST`-vesileimalla	Ilman vesileimaa
Sähköposti	Toimitetaan vain organisaatiosi jäsenille	Toimitetaan kaikille vastaanottajille
Laskutus	Ilmainen ja rajaton, ei koskaan lasketa	Valmiit kirjekuoret lasketaan pakettisi kiintiöön
Data	Avaimella luodut kirjekuoret, linkit ja webhook-päätepisteet ovat testitilassa	Tuotantotilassa

Tila määräytyy avaimesta, ei koskaan pyynnöstä: ?test_mode=true kutsussa POST /v1/envelopes koskee vain hallintapaneelin istuntoja. Luettelot (GET /v1/envelopes, GET /v1/signing-links) palauttavat vain avaimen tilan, ja kirjekuoren tapahtumat menevät vain saman tilan webhook-päätepisteisiin. Jokainen kirjekuori ja webhook-hyötykuorma kertoo, missä tilassa se on (testMode).

Avainten luominen ja peruuttaminen

Avaimia hallitaan hallintapaneelissa kohdassa Asetukset › API-avaimet, ja sen voivat tehdä jäsenet, joilla on käyttöoikeus apikey:manage (omistajat ja ylläpitäjät). Salaisuus näytetään kerran, kun avain luodaan. Voit antaa avaimelle nimen, tilan, vanhenemisajan (1–365 päivää tai ei lainkaan) ja käyttöoikeusalueet.

Käyttöoikeusalueet

Avaimen käyttöoikeusalueet ovat ne organisaation käyttöoikeudet, joita se saa käyttää. Oletuksena uusi avain saa luojansa käyttöoikeudet lukuun ottamatta hallinnollisia (org:manage, member:manage, sso:manage, apikey:manage, billing:manage), eikä kukaan voi antaa avaimelle käyttöoikeutta, jota hänellä itsellään ei ole. Avaimen käyttöoikeusalueiden ulkopuolinen kutsu on 403, joka nimeää puuttuvan käyttöoikeuden:

{
  "type": "https://bonafidesign.com/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Missing permission: envelope:send.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

Käyttöoikeus	Sallii avaimen
`template:read`	Luetella ja lukea malleja, versioita ja niiden PDF-tiedostoja
`template:write`	Luoda malleja, ladata tiedostoja, tallentaa luonnoksia, poistaa käyttämättömiä malleja
`template:publish`	Julkaista luonnoksen uutena versiona
`envelope:read`	Luetella ja lukea kirjekuoria, asiakirjoja ja kirjausketjuja; luetella allekirjoituslinkkejä
`envelope:send`	Luoda kirjekuoria, allekirjoitusistuntoja ja allekirjoituslinkkejä; lähettää linkkejä uudelleen
`envelope:void`	Mitätöidä keskeneräisiä kirjekuoria
`org:manage`	Hallita webhook-päätepisteitä ja toimittaa tapahtumia uudelleen; lukea organisaation asetuksia
`billing:manage`	Lukea käyttöä (`GET /v1/usage`) ja laskujen summia

Webhook-päätepisteiden hallinta vaatii käyttöoikeuden org:manage, jota avaimet eivät saa oletuksena: rekisteröi päätepisteet hallintapaneelissa tai luo avain, jolle annat tämän käyttöoikeusalueen erikseen.

Mitkä päätepisteet hyväksyvät mitäkin

Jokainen API-viitteen operaatio luettelee suojausmenetelmänsä. Lyhyesti:

API-avain tai hallintapaneelin istunto: mallit, kirjekuoret, allekirjoitusistunnot, allekirjoituslinkit, webhook-päätepisteet, organisaation asetukset, laskutuksen yleiskatsaus ja käyttö.
Vain hallintapaneelin istunto: API-avaimet, SCIM-tunnukset, SSO-yhteyden asetukset, organisaation logon lataaminen, laskutuksen kassa ja portaali, webhook-salaisuuden näyttäminen.
Allekirjoittajan tunnus: /v1/signing/*, jota isännöity sivu ja <bf-signing> käyttävät istuntotunnuksella (bfs_…) tai käyttötunnuksella, johon se vaihdetaan (bfa_…).
Julkinen: /v1/links/{id} (pysyvät linkit), /v1/sso/discover ja tarkistus-API (/v1/public/*, /.well-known/bona-fide/keys.json).

Kirjautuminen hallintapaneeliin

Ihmiset (eivät palvelimet) kirjautuvat hallintapaneeliin osoitteessa https://app.bonafidesign.com/sign-in. Oletus on sähköposti ja salasana; vaihtoehtoja ovat sähköpostitse lähetettävä kuusinumeroinen koodi (Lähetä minulle koodi sähköpostitse), taikalinkki, pääsyavain, Google tai Microsoft sekä yrityksesi SSO.

Tilin luominen salasanalla lähettää yhden sähköpostin: koodin, joka vahvistaa osoitteen olevan sinun. Siihen asti salasanalla ei voi kirjautua. Rekisteröityminen osoitteella, jolla on jo tili, ei muuta mitään ja saa täsmälleen saman vastauksen kuin uusi rekisteröityminen; osoitteen omistaja saa sähköpostin, jossa kerrotaan, miten hän voi sen sijaan kirjautua.
Salasanat ovat 12–128 merkin pituisia, ja ne tallennetaan suolattuina scrypt-tiivisteinä. Uusi salasana, joka esiintyy tunnetussa tietovuodossa, hylätään: vain sen SHA-1-tiivisteen viisi ensimmäistä merkkiä lähetetään palveluun Have I Been Pwned (k-anonymiteetti), ei koskaan salasanaa. Jos palvelu ei vastaa kahdessa sekunnissa, salasana hyväksytään ilman tarkistusta.
Unohditko salasanasi? Palautussähköpostissa on linkki sivulle, jolla valitset uuden. Linkki toimii kerran ja vanhenee tunnin kuluttua, ja sen käyttäminen kirjaa sinut ulos kaikilla laitteilla.
Eikö salasanaa vielä ole? Koodilla, linkillä, pääsyavaimella tai Googlella / Microsoftilla luodut tilit kirjautuvat jatkossakin samalla tavalla, ja niihin voi lisätä salasanan kohdassa Asetukset › Tili. Ensimmäisen salasanan asettaminen vaatii kirjautumisen viimeisen 15 minuutin aikana (sivu lähettää sinulle koodin sähköpostitse henkilöllisyytesi vahvistamiseksi); sen vaihtaminen vaatii nykyisen salasanan. Molemmat kirjaavat ulos muut istuntosi.
Virheet eivät koskaan paljasta tilejä: väärä salasana, tuntematon osoite ja tili ilman salasanaa saavat saman vastauksen, ja palautuspyyntö kertoo aina, että sähköposti on matkalla.
Nopeusrajoitukset: salasanalla kirjautumista, rekisteröitymistä ja palautuspyyntöjä rajoitetaan IP-osoitetta ja sähköpostiosoitetta kohden; rajan ylittyessä vastaus on 429, kunnes aikaikkuna on kulunut.
Yrityksen SSO: kun organisaatiosi pakottaa SSO:n, jäsenet, joiden sähköposti on organisaation verkkotunnuksissa, kirjautuvat vain identiteetintarjoajan kautta. Salasanat, koodit ja taikalinkit hylätään heidän kohdallaan; omistajat säilyttävät sähköpostikoodin hätäkirjautumisena.

Pyyntötunnukset

Jokaisessa vastauksessa on x-request-id-otsake ja jokaisessa virherungossa requestId. Voit lähettää oman x-request-id-arvosi (8–128 merkkiä joukosta A-Z a-z 0-9 . _ -) lokien yhdistämiseksi; muuten API luo sellaisen. Mainitse se ottaessasi yhteyttä tukeen.