Szolgáltatásfiókok és szervezeti API-kulcsok
Gépi integrációhoz — ami nem egy emberhez tartozik, és akkor is futnia kell, ha egy kolléga kilép — a szervezet API-kulcsát használd. Egy API-kulcs egy szolgáltatásfiók tokenje: egy nem emberi felhasználóé, aki a szervezet tagja, és szerepkört kap.
Kiadás a tenant-felületen
A szervezet felületén az Integrációk › Webhookok és API képernyőn:
- Név — a kulcs és a hozzá létrejövő szolgáltatásfiók neve.
- Szerepkör — a kulcs jogköre ebből jön. Csak a szervezet saját szerepkörei választhatók, és csak olyan, amit a kiadó maga is kioszthat: a kulcs jogköre nem lehet bővebb a kiadóénál.
- Lejárat — alapból 90 nap, legfeljebb 365 nap.
A kiadáshoz újrahitelesítés (step-up) kell. A kulcs értéke csak egyszer, a kiadás válaszában látszik.
A kulcsot ugyanúgy használod, mint bármely tokent:
curl https://acme.app.vecton.hu/api/webshop/orders \
-H "Authorization: Bearer $VECTON_API_KEY" \
-H "Accept: application/json"
A kulcsok használata külön kéréskorlát-vödörbe számít, és a felület mutatja, mikor használták utoljára.
Hatókör (szűkítés)
Egy API-kulcs a szerepkörénél szűkebbre is korlátozható hatókörökkel
(scopes). Ha a kulcsnak van hatóköre, a tenant-host minden kérésnél
ellenőrzi, hogy a kért jog szerepel-e benne; ha nem, a válasz:
{
"message": "A szolgáltatás-fiók tokenje nem tartalmazza ezt a jogosultságot.",
"error": "service_account_scope_denied",
"required_permission": "tenant.acme.webshop.orders.update"
}
A hatókör teljes jogosultság-név vagy minta:
| Hatókör | Mit fed |
|---|---|
tenant.acme.webshop.orders.list | pontosan ezt az egy jogot |
tenant.acme.crm.tasks.* | a crm.tasks csoport minden jogát az acme szervezetben |
tenant.*.warehouse.* | a raktár modul minden jogát |
* | mindent (a szerepkör korlátja továbbra is él) |
A * egy szegmenst helyettesít, a záró .* minden mélyebb szegmenst is
lefed. A hatókör sosem ad több jogot, mint a szerepkör: a kettő metszete
érvényes. A jogosultságok nevéről: Jogosultságok.
Hatókörös kulcsot az identity szolgáltatásfiók-API-ja ad ki, a szervezet szolgáltatásfiók-kezelési jogával:
POST https://identity.vecton.hu/api/tenants/{tenantId}/service-accounts/{userId}/api-keys
Authorization: Bearer <a kiadó tokenje>
Content-Type: application/json
{
"name": "ERP-összekötő",
"expires_at": "2027-06-30T23:59:59Z",
"scopes": ["tenant.acme.webshop.orders.list", "tenant.acme.webshop.orders.view"]
}
Olyan hatókör, amit a kiadó maga sem birtokol, nem adható ki (403). A
kulcsot kiadás után egy hívással próbáld ki: egy elírt hatókör-név a kért
jogot nem fedi, és a hívás service_account_scope_denied lesz.
| Végpont | Mire való |
|---|---|
GET /api/tenants/{tenantId}/service-accounts | szolgáltatásfiókok listája |
POST /api/tenants/{tenantId}/service-accounts | új szolgáltatásfiók |
GET /api/tenants/{tenantId}/service-accounts/{userId}/api-keys | a fiók kulcsai (érték nélkül) |
POST /api/tenants/{tenantId}/service-accounts/{userId}/api-keys | új kulcs |
POST /api/tenants/{tenantId}/service-accounts/{userId}/api-keys/{keyId}/rotate | kulcs cseréje azonos névvel és lejárattal |
DELETE /api/tenants/{tenantId}/service-accounts/{userId}/api-keys/{keyId} | kulcs visszavonása |
Csere és visszavonás
- Csere (rotate): a régi kulcs azonnal érvénytelen, az új értéke egyszer látszik; a név és a lejárat átkerül. A hatókör nem kerül át — hatókörös kulcs helyett adj ki új kulcsot a hatókörrel, és utána vond vissza a régit. Cserélj rendszeresen, és mindig, ha a kulcs gyanúsan kiszivárgott.
- Visszavonás: a következő kérés már
401 unauthenticated. - A lejárt kulcs automatikusan
401-et kap; a lejárat előtt adj ki újat.
A hatókör a gépi tokenek eszköze. Emberi felhasználó nevében kért OAuth-tokenbe ne kérj hatókört — lásd: Emberi kliens ne kérjen hatókört.