# Hitelesítés

A SURVIOT API-hoz való hozzáféréshez hitelesítés szükséges.

A hitelesítést a SURVIOT az ügyfelek számára az [OAuth 2.0 Client Credentials](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) eljáráson keresztül teszi lehetővé.

## OAuth 2-alkalmazás regisztrációja

A SURVIOT jelenleg nem támogatja OAuth 2-alkalmazások önálló regisztrációját. A regisztrációhoz keresse fel a rendszergazdáját, vagy írjon az <info@surviot.com> e-mail címre.

Az alkalmazásregisztráció eredményeképp egy *ügyfélazonosítóból* (client id) és *ügyfélkódból* (client secret) álló hitelesítőadat-pár áll elő. A továbbiakban ezeket használhatja személyazonossága igazolásához.

{% hint style="warning" %}
Ügyfélazonosítója és ügyfélkódja érzékeny adat, melynek birtokában bárki hozzáférhet SURVIOT-projektjéhez. Hitelesítőadat-párját kezelje titkosan, és ne adja át harmadik félnek.
{% endhint %}

## Hozzáférési token beszerzése

Az API használatához *hozzáférési tokenre* (access tokenre) van szüksége, amely a hitelesítési folyamat eredményeképp áll elő.

A hitelesítés megkezdéséhez küldjön kérést a `https://surviot.auth.eu-central-1.amazoncognito.com/oauth2/token` címre, és adja át hitelesítőadat-párját a `client_id` illetve `client_secret` paraméterek értékeként:

{% tabs %}
{% tab title="cURL" %}
{% code lineNumbers="true" fullWidth="true" %}

```bash
curl \
  --location 'https://surviot.auth.eu-central-1.amazoncognito.com/oauth2/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=<client_id>' \
  --data-urlencode 'client_secret=<client_secret>'
```

{% endcode %}
{% endtab %}

{% tab title="Javascript" %}

```javascript
const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/x-www-form-urlencoded");

const urlencoded = new URLSearchParams();
urlencoded.append("grant_type", "client_credentials");
urlencoded.append("client_id", "<client_id>");
urlencoded.append("client_secret", "<client_secret>");

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: urlencoded,
  redirect: "follow"
};

fetch("https://surviot.auth.eu-central-1.amazoncognito.com/oauth2/token", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
A hozzáférési tokenek érvényességei ideje 1 óra. Az érvényességi idő lejártát követően a token nem használható. Az API-hoz való hozzáféréshez új token beszerzésére van szükség.
{% endhint %}

## Alkalmazásengedélyek (scope-ok)

Az sikeres OAuth 2.0-hitelesítés eredményeképp megkapott hozzáférési tokenje az alábbi jogkörökkel rendelkezhet a SURVIOT beállításaitól függően:

<table><thead><tr><th width="163">Jogkör</th><th>Leírás</th></tr></thead><tbody><tr><td><code>api:read</code></td><td>Olvasási hozzáférés a SURVIOT-projektje adataihoz</td></tr><tr><td><code>api:write</code></td><td>Írási hozzáférés a SURVIOT-projektje adataihoz</td></tr></tbody></table>

{% hint style="info" %}
A hozzáférési tokenben a jogköreit előtagként az ön SURVIOT-projektje azonosítójával látjuk el, így a jogkörök a `com.surviot.projektnév/api:read` alakot kapják.
{% endhint %}

## A SURVIOT API használata

Hozzáférési tokenje birtokában megkezdheti a SURVIOT API használatát.

Személyazonosságát az `Authorization` HTTP-fejlécben megadott hozzáférési tokenje segítségével igazolhatja.

Kezdésképp kérdezze le [mérési helyeit](https://docs.surviot.com/tovabbi-oldalak/szojegyzek#meresi-hely) az API segítségével:

{% tabs %}
{% tab title="cURL" %}

```bash
curl \
  --location 'https://<projektnév>.surviot.com/api/locations?time=1w' \
  --header 'Authorization: Bearer <access_token>'
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer <access_token>");

const requestOptions = {
  method: "GET",
  headers: myHeaders,
  redirect: "follow"
};

fetch("https://<projektnév>.surviot.com/api/locations?time=1w", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));
```

{% endtab %}
{% endtabs %}

## API dokumentáció

Az API-n keresztül elérhető funkciók dokumentációjáért keresse fel az [API-dokumentáció](https://docs.surviot.com/surviot-api/api-dokumentacio) oldalt.
