# Todennus

Jokaisen API-pyynnön on sisällettävä API-avaimesi, jotta <span data-t="appName">Your AI Connector</span> 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](#the-paid-feature-gate). Ohjeet avaimen luomiseen löytyvät kohdasta [API-käyttöoikeus](../integrations/api-access.md).

> **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

| Menetelmä | Välitystapa | Milloin käyttää |
|---|---|---|
| Kyselyparametri | `?apiKey=YOUR_API_KEY` | Pikatestit ja selaimen URL-osoitteet |
| Otsake | `X-API-Key: YOUR_API_KEY` | Tuotantointegraatiot |
| Bearer-otsake | `Authorization: Bearer YOUR_API_KEY` | Tuotantointegraatiot |
| Firebase ID -tunniste | `Authorization: Bearer <ID token>` | Vain ensisijaiset sovellusistunnot |

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**

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

**JavaScript**

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

**Python**

```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**

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

**JavaScript**

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

**Python**

```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**

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

**JavaScript**

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

**Python**

```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 <span data-t="appName">Your AI Connector</span>: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 <span data-t="appName">Your AI Connector</span>-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](api-keys.md), 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`:

```json
{
  "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 [<span data-t="supportEmail">hi@youraiconnector.com</span>](mailto:hi@youraiconnector.com). A missing or wrong key returns `401` instead:

```json
{
  "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](#key-scopes).
- **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](api-keys.md).
- **Käytä aina HTTPS-yhteyttä**, jotta avain on salattu siirron aikana.

---

## Seuraavat vaiheet

- [Aloittaminen](getting-started.md) – ensimmäinen pyyntösi ja resurssioppaat.
- [Virheet ja sivutus](errors-and-pagination.md) – virheiden käsittely ja tulosten selaaminen sivuittain.
- [API-avaimet](api-keys.md) – avaimen vaihtaminen, kumoaminen ja käytön tarkistaminen.