API-avainten rajapinta #

Näiden päätepisteiden avulla voit hallita tilisi API-avaimia koodin kautta. Ne kaikki toimivat vain kutsuvan tilin omien avainten osalta.

Avaimia on kahta tyyppiä, ja ne sijaitsevat eri poluilla:

• Pääavaimesi — yksittäinen täyden käyttöoikeuden avain kohdassa Asetukset → Integraatiot → API-avain. Voit tarkastella sen peitettyä esikatselua, tarkistaa nopeusrajoitusten käytön, vaihtaa avaimen tai mitätöidä sen. Nämä ovat alla olevia /api-keys/current-, /api-keys/rotate- ja /api-keys/usage-päätepisteitä.
• Rajoitetut avaimet (Scoped keys) — ylimääräisiä, nimettyjä avaimia, joita luot tiettyä tehtävää varten. Jokainen niistä on rajoitettu vain valitsemiisi API-osiin. Nämä ovat rajoitettujen avainten alla olevia /api-keys- ja /api-keys/{id}-päätepisteitä. Pääavaimesi ei muutu, kun luot tällaisen avaimen; olemassa olevat integraatiot toimivat edelleen ennallaan.

Kaikki alla olevat polut ovat suhteessa rajapinnan perus-URL-osoitteeseen:

https://api.youraiconnector.com/v1

Jokainen pyyntö on todennettava. Katso kohdasta Todennus neljä hyväksyttyä menetelmää. Tässä olevissa esimerkeissä käytetään X-API-Key-otsikkoa (ja yhtä kyselyparametrimuotoa cURL-kutsulle).

Lue tämä ensin. Avaimen vaihtaminen tai mitätöinti astuu voimaan välittömästi. Heti kun kutsu onnistuu, vanha avain lakkaa toimimasta – jokainen sitä käyttävä integraatio alkaa saada 401-virheitä. Suunnittele tämä: vaihda avain huoltoikkunan aikana ja päivitä kaikki integraatiosi välittömästi.

Hae nykyisen avaimen metatiedot #

Palauttaa tiedot aktiivisesta avaimestasi: peitetyn esikatselun (ensimmäiset 4 ja viimeiset 4 merkkiä), tiedon siitä, voidaanko koko avain näyttää uudelleen sovelluksessa (api_key_retrievable), sekä luontipäivämäärän, jos se on saatavilla. API ei koskaan palauta koko avainta: jos haluat nähdä tai kopioida sen, avaa sovelluksessa Asetukset → Integraatiot → API-avain ja napsauta Näytä tai Kopioi. api_key_retrievable on false avaimille, jotka on luotu ennen kuin haettavissa olevia kopioita säilytettiin – kierrätä avain kerran, niin uusi avain voidaan näyttää uudelleen myöhemmin.

GET /api-keys/current

cURL

curl "https://api.youraiconnector.com/v1/api-keys/current?apiKey=YOUR_API_KEY"

JavaScript

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

Python

import requests

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

Vastaus

{
  "success": true,
  "api_key_masked": "abcd...qrst",
  "api_key_retrievable": true,
  "created_at": "2026-06-01T10:00:00.000Z"
}

Jos tilillä ei ole API-avainta, vastaus on 404 ja sisältää { "success": false, "error": "No API key found for this account" }.

Hae nopeusrajoituksen käyttö #

Palauttaa nykyisen ikkunan nopeusrajoituksen käytön: pyyntörajan per ikkuna, tähän mennessä laskettujen pyyntöjen määrän, jäljellä olevien pyyntöjen määrän sekä ikkunan nollautumisajan. Käytä tätä asiakaspuolen rajoitusten (throttling) rakentamiseen, jotta integraatiosi hidastaa toimintaansa ennen kuin se kohtaa 429-vastauksia.

GET /api-keys/usage

cURL

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

JavaScript

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

Python

import requests

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

Vastaus

{
  "success": true,
  "usage": {
    "limit": 300,
    "window_seconds": 60,
    "used": 37,
    "remaining": 263,
    "window_resets_at": "2026-06-09T12:01:00.000Z"
  }
}

Jos nykyisessä ikkunassa ei ole vielä kirjattu yhtään pyyntöä, käytöksi ilmoitetaan nolla ja vastaus sisältää note-kentän, joka selittää syyn.

Vaihda avain #

Luo uuden API-avaimen ja mitätöi edellisen samassa vaiheessa. Käytä tätä, jos epäilet avaimen vuotaneen, tai osana säännöllistä tunnusten vaihtokäytäntöä.

POST /api-keys/rotate

Uusi avain näytetään vain kerran. Se palautetaan tässä vastauksessa, eikä sitä voi hakea kokonaisuudessaan myöhemmin – tallenna se turvallisesti heti, kun saat sen. Edellinen avain lakkaa toimimasta heti, kun tämä kutsu onnistuu, joten päivitä jokainen integraatio, joka käytti sitä.

cURL

curl -X POST "https://api.youraiconnector.com/v1/api-keys/rotate?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/api-keys/rotate", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
// Save data.api_key now — it will not be shown again.

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/api-keys/rotate",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Save data["api_key"] now — it will not be shown again.

Vastaus

{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "message": "API key rotated. The previous key is no longer valid. Store this key now — it will not be shown again."
}

Peruuta avain #

Poistaa pysyvästi tilisi API-avaimen. Peruutus on välitön: jokainen seuraava pyyntö, joka käyttää peruutettua avainta – mukaan lukien integraatiot, kuten Make, Zapier tai mukautetut skriptit – hylätään virheellä 401. Jos haluat palauttaa API-yhteyden myöhemmin, luo uusi avain tilisi asetuksista ollessasi kirjautuneena sovellukseen.

DELETE /api-keys/current

Toimintoa ei voi kumota. Toisin kuin avaimen vaihto, peruutus ei anna sinulle korvaavaa avainta. Peruuta avain vain, kun aiot lopettaa API-yhteyden (esimerkiksi vuotanut avain, jota et voi heti korvata).

cURL

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

JavaScript

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

Python

import requests

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

Vastaus

{
  "success": true,
  "revoked": true,
  "message": "API key revoked. All requests using it will be rejected immediately."
}

Jos tilillä ei ole peruutettavaa avainta, vastauksena on 404.

Rajoitetut avaimet #

Rajoitettu avain on ylimääräinen API-avain, jonka luot yhtä tiettyä tehtävää varten ja jolla on vain kyseiseen tehtävään tarvittavat käyttöoikeudet. Tyypillinen tilanne: haluat yhdistää asiakaskohtaisen hallintapaneelin, raportointityökalun tai sisäisen skriptin tiliisi ilman, että annat avainta, jolla voisi myös lähettää viestejä, muuttaa tekoälyagenttejasi tai ostaa puhelinnumeroita.

Rajoitus seuraa itse avainta, joten sen haltija voi tehdä vain sen, minkä sallit avainta luodessasi.

Mitä voit rajoittaa

Voit myös asettaa avaimelle expires_at-päivämäärän (ISO 8601, ja sen on oltava tulevaisuudessa). Tämän hetken jälkeen avain lakkaa toimimasta. Jos jätät tämän määrittämättä, avain ei vanhene koskaan, ellet itse mitätöi sitä.

Kieltäminen on oletusarvoista. Jos pyyntö ei kuulu avaimen sallimiin rajoihin, se hylätään sen sijaan, että se sallittaisiin: kirjoituspyyntö vain luku -avaimella palauttaa 403 ja error_code: "key_read_only", ja kaikki avaimen sallittujen osioiden ulkopuolelle jäävä palauttaa 403 ja error_code: "key_scope_denied". Hallinnoitujen tilien luetteloon rajoitettu avain saa saman key_scope_denied-vastauksen, kun kutsusta puuttuu sub_account_id tai siinä nimetään tili, joka ei ole listalla, tai kun käytetään päätepisteitä, jotka hallinnoivat hallinnoimiasi tilejä ja tilannevedoksia. Jos rajattu avain saa odottamattoman 403-vastauksen, kutsumasi päätepiste ei yksinkertaisesti kuulu sen laajuuteen — laajenna avaimen käyttöoikeuksia tai käytä pääavaintasi.

Vain tilin omistaja hallinnoi avaimia. Nämä neljä päätepistettä vaativat pääavaimesi tai omistajan istunnon sovelluksessa. Rajoitettu avain ei voi koskaan listata, luoda, muokata tai mitätöidä avaimia — mukaan lukien itseään — joten rajoitettua avainta ei voi koskaan käyttää laajemman avaimen luomiseen. Yritys palauttaa 403 ja error_code: "key_scope_denied". Samasta syystä API Keys ei ole osio, jonka voit myöntää: sen pyytäminen palauttaa 400 ja error_code: "invalid_scopes".

Listaa rajoitetut avaimet #

Palauttaa tilin rajoitetut avaimet uusimmasta alkaen (enintään 200), mukaan lukien mitätöidyt, jotta näet, mikä on poistettu ja milloin. Vain peitetyt esikatselut palautetaan — rajoitetun avaimen arvo näytetään vain kerran luontihetkellä, eikä sitä voi hakea sen jälkeen.

GET /api-keys

cURL

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

Vastaus

{
  "success": true,
  "api_keys": [
    {
      "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
      "label": "Client dashboard - Acme",
      "key_preview": "abcd...qrst",
      "scopes": {
        "read_only": true,
        "tags": ["Analytics"],
        "sub_account_ids": [],
        "rate_limit_per_min": 60
      },
      "expires_at": null,
      "last_used_at": "2026-08-20T14:03:00.000Z",
      "created_at": "2026-08-14T09:12:00.000Z",
      "revoked_at": null,
      "revoked": false
    }
  ]
}

Luo rajoitettu avain #

Luo uuden rajatun avaimen ja palauttaa sen arvon kerran.

POST /api-keys

Avain näytetään vain kerran. Se on tässä vastauksessa eikä missään muualla, koskaan — sitä ei voi hakea jälkikäteen. Tallenna se heti, kun vastaanotat sen. Jos kadotat sen, peruuta se ja luo uusi.

Runkokentät — kaikki valinnaisia:

cURL

curl -X POST "https://api.youraiconnector.com/v1/api-keys" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Client dashboard - Acme",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics"],
      "sub_account_ids": [],
      "rate_limit_per_min": 60
    }
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/api-keys", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    label: "Client dashboard - Acme",
    scopes: { read_only: true, tags: ["Analytics"] },
  }),
});
const data = await res.json();
// Save data.api_key now — it will not be shown again.

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/api-keys",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "label": "Client dashboard - Acme",
        "scopes": {"read_only": True, "tags": ["Analytics"]},
    },
)
data = res.json()
# Save data["api_key"] now — it will not be shown again.

Vastaus — 201 Created

{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "key": {
    "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
    "label": "Client dashboard - Acme",
    "key_preview": "abcd...qrst",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics"],
      "sub_account_ids": [],
      "rate_limit_per_min": 60
    },
    "expires_at": null,
    "revoked": false
  },
  "message": "Store this key now — it is shown once and cannot be retrieved again."
}

Muutama yksityiskohta, jotka on hyvä tietää, kun rakennat tätä vasten:

• scopes-kohdan jättäminen pois ei ole sama asia kuin tyhjän tags-luettelon lähettäminen. Jätä scopes kokonaan pois, niin saat turvallisen oletuksen (vain luku, vain Analytics). Lähetä "tags": [] tarkoituksella, niin avain voi käyttää jokaista osiota — se tulkitaan tietoiseksi pyynnöksi rajoittamattomasta avaimesta.
• read_only pysyy true-tilassa, ellet nimenomaisesti lähetä false-arvoa. Kirjoitusvirhe tai puuttuva lippu ei voi koskaan vahingossa tuottaa avainta, jolla on kirjoitusoikeus.

Rajatun avaimen päivittäminen #

Muuttaa avaimen nimeä, laajuuksia ja/tai vanhenemispäivää. Lähetä mikä tahansa yhdistelmä näistä kolmesta; jos et lähetä mitään, palautetaan 400.

PATCH /api-keys/{id}

{id} on avaimen id luettelosta (arvo key_...), ei koskaan itse avain.

Laajuudet korvataan, ei yhdistetä. Kaikki, mitä lähetät, muodostaa avaimen täydellisen käyttöoikeusjoukon. Tämä on harkittua: avaimen rajoittaminen ei voi koskaan jättää vanhaa, laajempaa käyttöoikeutta voimaan huomaamatta. Lähetä aina koko scopes-objekti, jonka haluat, älä vain kenttää, jota olet muuttamassa.

Avaimen arvo ei koskaan muutu. Rajatulle avaimelle ei ole olemassa paikallista vaihtoa — jos haluat vaihtaa avaimen, luo uusi avain ja peruuta vanha, jotta tunnistetiedon käyttöoikeudet eivät voi koskaan muuttua integraatiossa, joka sitä vielä käyttää.

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/api-keys/key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Client dashboard - Acme (read-only)",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics", "Campaigns"],
      "sub_account_ids": [],
      "rate_limit_per_min": 30
    }
  }'

Vastaus

{
  "success": true,
  "key": {
    "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
    "label": "Client dashboard - Acme (read-only)",
    "key_preview": "abcd...qrst",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics", "Campaigns"],
      "sub_account_ids": [],
      "rate_limit_per_min": 30
    },
    "expires_at": null,
    "last_used_at": "2026-08-20T14:03:00.000Z",
    "created_at": "2026-08-14T09:12:00.000Z",
    "revoked_at": null,
    "revoked": false
  }
}

Jos tililläsi ei ole avainta kyseisellä tunnisteella, vastauksena on 404.

Rajatun avaimen mitätöinti #

Mitätöinti tapahtuu välittömästi: seuraava kyseistä avainta käyttävä pyyntö hylätään virheellä 401. Pääavaimesi ja kaikki muut rajatut avaimet säilyvät ennallaan.

DELETE /api-keys/{id}

Avain pysyy luettelossasi merkittynä tilalla "revoked": true, joten säilytät tiedon siitä, mitä avaimia on ollut olemassa ja mihin ne ovat päässeet käsiksi. Jo mitätöidyn avaimen mitätöiminen onnistuu, mutta se ei muuta mitään.

cURL

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

Vastaus

{
  "success": true,
  "revoked": true,
  "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
  "message": "API key revoked. All requests using it will be rejected immediately."
}

API-avainten API-virheet #

API-avainten päätepisteet palauttavat vakioidun virhekuoren:

{
  "success": false,
  "error": "No API key found for this account"
}

API-avainten päätepisteessä puuttuva tai virheellinen avain palauttaa 401 ja tili, jolla ei ole tallennettua avainta, palauttaa 404. Jaetut koodit, joita jokainen päätepiste voi palauttaa — 400, 403 (tilauksesi ei sisällä API-käyttöoikeutta), 429 (nopeusrajoitus) ja 500 — on lueteltu uudelleenyritysohjeiden kera kohdassa Virheet ja sivutus.

Rajatun avaimen päätepisteet lisäävät muutamia nimettyjä koodeja error_code-kenttään, jotta voit erottaa tapaukset toisistaan:

Seuraavat vaiheet #

• Todennus — neljä tapaa todentaa pyyntö ja miten avainten laajuudet (scopes) toteutetaan.
• Virheet ja nopeusrajoitukset — tilakoodit ja 300 pyyntöä/minuutti -rajoitus.