Todennus #

Jokaisen API-pyynnön on sisällettävä API-avaimesi, jotta Your AI Connector tietää, kuka olet ja mitä tiliä pyyntö koskee. Voit lähettää avaimen neljällä eri tavalla – kaikki toimivat jokaisessa päätepisteessä, joka hyväksyy API-avaintodennuksen, joten valitse niistä omaan käyttöösi parhaiten sopiva.

API-käyttöoikeus on maksullinen ominaisuus. Jos tilauksesi ei sisällä sitä, pyynnöt hylätään virheellä 403, vaikka itse avain olisi voimassa – katso alta kohta Maksullisten ominaisuuksien rajoitukset. Ohjeet avaimen luomiseen löytyvät kohdasta API-käyttöoikeus.

Vain HTTPS. Kaikkien pyyntöjen on käytettävä suojattua yhteyttä. Tavalliset HTTP-pyynnöt hylätään ennen kuin todennus edes alkaa.

Neljä menetelmää pähkinänkuoressa #

Jos käytössä on useampi kuin yksi, kyselyparametri on ensisijainen, sen jälkeen X-API-Key-otsake ja lopuksi bearer-tunniste. Käytännössä lähetät kuitenkin aina vain yhden.

1. Kyselyparametri — ?apiKey= #

Lisää avain verkko-osoitteen loppuun. Tämä on yksinkertaisin tapa ja se toimii aina, mikä tekee siitä ihanteellisen pikatesteihin, skripteihin ja vanhempiin työkaluihin.

cURL

curl "https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY");
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    params={"apiKey": "YOUR_API_KEY"},
)
data = res.json()

Huomio: Verkko-osoitteet tallentuvat selaimen historiaan, palvelimen lokitiedostoihin ja välityspalvelimen lokeihin. Jos kyseessä on muu kuin pikatesti, suosi jotakin alla olevista otsakemenetelmistä, jotta avainta ei tallenneta levylle selväkielisenä.

2. X-API-Key-otsake #

Lähetä avain erillisessä otsakkeessa. Tämä pitää sen poissa URL-osoitteesta ja on suositeltu valinta tuotantoympäristöihin.

cURL

curl "https://api.youraiconnector.com/v1/contacts" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

3. Authorization: Bearer-otsikko #

Voit myös välittää avaimen tavallisena bearer-tunnisteena. Tämä on kätevää, kun HTTP-asiakasohjelmassasi tai kehyksessäsi on jo sisäänrakennettu tuki Authorization-otsikoille.

cURL

curl "https://api.youraiconnector.com/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
  },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = res.json()

API erottaa API-avaimesi kirjautumistunnisteesta automaattisesti, joten tämä menetelmä toimii täsmälleen kuten X-API-Key.

4. Firebase ID -tunniste (vain ensimmäisen osapuolen sovellukset) #

Jos kehität ensimmäisen osapuolen sovellusta, joka kirjautuu käyttäjät sisään Your AI Connector:n oman kirjautumisen kautta, voit välittää kyseisen sisäänkirjautuneen käyttäjän Firebase ID -tunnisteen bearer-tunnisteena API-avaimen sijaan:

Authorization: Bearer <Firebase ID token>

Tunniste vahvistetaan jokaisessa pyynnössä ja se yhdistetään sisäänkirjautuneeseen tiliin. Tämä menetelmä on tarkoitettu vain ensimmäisen osapuolen sovellusistunnoille — et voi luoda näitä tunnisteita ulkoisesta integraatiosta, eikä niitä voi hankkia muuten kuin normaalin sovelluskirjautumisen kautta. Käytä palvelimien välisiin ja kolmannen osapuolen integraatioihin API-avainta (menetelmät 1–3).

Milloin mitäkin käytetään #

• Nopeat testit ja kertaluonteiset skriptit → kyselyparametri (?apiKey=). Nopein kirjoittaa, toimii selaimessa.
• Tuotanto-integraatiot ja palvelimien väliset kutsut → X-API-Key tai Authorization: Bearer YOUR_API_KEY. Pitää avaimen poissa URL-osoitteista ja lokeista.
• Ensimmäisen osapuolen sovellukset, joissa on sisäänkirjautunut Your AI Connector-käyttäjä → Authorization: Bearer <Firebase ID token>.

Avainten laajuudet #

Tililläsi on yksi pää-API-avain – se löytyy kohdasta Asetukset → Integraatiot → API-avain. Sillä on täydet käyttöoikeudet kaikkeen, mitä tili voi tehdä.

Voit myös luoda ylimääräisiä rajattuja avaimia: nimettyjä avaimia, jotka pääsevät vain valitsemiisi API-osiin, esimerkiksi vain luku -oikeudella varustettu avain, joka on rajoitettu analytiikkaan raportointikoontinäyttöä varten. Rajattu avain lähetetään täsmälleen samalla tavalla kuin pääavain (millä tahansa yllä mainituista tavoista 1–3), mutta sen käyttöoikeudet tarkistetaan jokaisen pyynnön yhteydessä:

• Sallittujen alueiden ulkopuolella käyttö evätään. Kirjoituspyyntö vain luku -avaimella tai kutsu osioon, johon avaimella ei ole oikeuksia, palauttaa virheen 403 – key_read_only tai key_scope_denied kentässä error_code. Tarkistus on tarkoituksella tiukka: kaikki, mikä ei selvästi kuulu avaimen sallittuihin alueisiin, evätään sen sijaan, että se sallittaisiin. Jos siis näet jonkin näistä 403-virheistä, avain ei yksinkertaisesti kata kyseistä päätepistettä.
• Sillä on oma nopeusrajoitusbudjetti. Rajatun avaimen käyttö lasketaan erillään pääavaimestasi, joten kiireinen koontinäyttö, joka käyttää rajattua avainta, ei kuluta kiintiötä, josta muut integraatiosi ovat riippuvaisia. Valitset tämän minuuttikohtaisen budjetin avainta luodessasi.
• Se ei voi hallita API-avaimia. Vain tilin omistaja – kirjautuneena tai pääavainta käyttäen – voi listata, luoda, muokata, vaihtaa tai mitätöidä avaimia. Rajattu avain ei voi koskaan luoda itselleen laajempaa avainta.

Katso kohdasta API-avaimet, miten luot, muokkaat ja mitätöit rajattuja avaimia.

Maksullisten ominaisuuksien rajoitus #

API-käyttöoikeus on maksullinen ominaisuus. Jos tilauksesi ei sisällä sitä, muuten kelvollisella avaimella tehty pyyntö hylätään virheellä 403:

{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}

If you see this, check your plan or contact hi@youraiconnector.com. A missing or wrong key returns 401 instead:

{
  "success": false,
  "error_code": 401,
  "error": "Invalid API key"
}

Avaimen pitäminen turvassa #

• Käsittele avainta kuin salasanaa. Pääavaimesi antaa täyden pääsyn tilillesi. Jos sinun on annettava avain työkalulle tai henkilölle, joka tarvitsee vain osan oikeuksista, luo sen sijaan rajattu avain – katso Avainten laajuudet.
• Pidä se palvelinpuolella. Älä koskaan upota sitä selaimen JavaScriptiin, mobiilisovelluksen pakettiin tai mihinkään koodiin, jonka loppukäyttäjä voi lukea.
• Säilytä se salaisuuksien hallintajärjestelmässä tai palvelinpuolen asetuksissa, ei lähdekoodin hallinnassa.
• Vaihda avain, jos se vuotaa. Luo uusi avain hallintapaneelista tai kutsu POST https://api.youraiconnector.com/v1/api-keys/rotate – tämä mitätöi vanhan avaimen välittömästi. Katso API-avaimet.
• Käytä aina HTTPS-yhteyttä, jotta avain on salattu siirron aikana.

Seuraavat vaiheet #

• Aloittaminen – ensimmäinen pyyntösi ja resurssioppaat.
• Virheet ja sivutus – virheiden käsittely ja tulosten selaaminen sivuittain.
• API-avaimet – avaimen vaihtaminen, kumoaminen ja käytön tarkistaminen.