Aan de slag met de API

API-sleutels en authenticatie

Elke aanvraag bevat een organisatie-API-sleutel als Bearer-token in de Authorization-header. Sleutels worden in de cloudconsole gemaakt en kunnen tot uw netwerken worden beperkt.

Verstuur bij elke aanvraag de sleutel als Bearer-token in de Authorization-header. De sleutel hoort bij één organisatie en de API leest de organisatie uit de sleutel zelf. Er is dus geen extra header nodig om de organisatie aan te geven; een meegestuurde X-ORGANIZATION-ID-header wordt genegeerd.

curl --request GET \
  --url https://api.serverside.com/v1/baremetal \
  --header 'Authorization: Bearer <api-key>'

De API leest de sleutel ook uit een X-API-KEY-header, een alias voor hetzelfde toegangsbewijs. Een aanvraag bevat slechts één toegangsbewijs: X-API-KEY samen met Authorization, of een van beide headers dubbel, wordt geweigerd met 400 (Authenticatiefouten).

Een sleutel maken

De eerste sleutel komt uit de cloudconsole: in de organisatie-instellingen staat onder Manage API Keys de knop Create an API Key. U geeft een naam op en eventueel de netwerken waarvandaan de sleutel werkt. De aangemaakte sleutel wordt één keer getoond en kan niet opnieuw worden weergegeven. Sla hem daarom direct op in een geheimenbeheerder of omgevingsvariabele.

Een sleutel telt 63 tekens: org_, gevolgd door 59 tekens URL-veilige base64, waaronder - en _. Alleen een Bearer-waarde die met org_ begint wordt als API-sleutel gelezen. Elke andere waarde geldt als consolesessietoken; een sleutel zonder voorvoegsel mislukt dus met 401.

Sleutels worden uitsluitend in de console beheerd. Endpoints voor het maken, opvragen en wijzigen van sleutels vereisen een aangemelde consolesessie. Een sleutel kan daarom geen andere sleutel maken, opvragen of wijzigen.

Bewerkingen die een sleutel niet kan aanroepen

De API-referentie vermeldt alle bewerkingen die een sleutel kan aanroepen. De rest van de API bedient de cloudconsole: organisatie-instellingen, leden, uitnodigingen, rollen, API-sleutels, meldingen, gebruikersprofiel, supporttickets en landen- en valutalijsten. Elk van deze bewerkingen antwoordt een sleutel met 401 en deze body:

{
  "success": false,
  "data": null,
  "code": "UNAUTHENTICATED",
  "message": "This endpoint requires a signed-in user session. Organization API keys are not accepted here.",
  "traceId": "SRV-1A2B-3C4D-5E6F-7A8B"
}

Sleutelmachtigingen

Een nieuwe sleutel krijgt alle machtigingen van de ingebouwde Admin-rol op de aanmaakdatum. Daarom noemt de console elke sleutel Full Permissions. Deze verzameling wordt daarna nooit bijgewerkt. Machtigingen die later aan het platform worden toegevoegd ontbreken bij oudere sleutels; een endpoint dat die controleert antwoordt zo'n sleutel met 403. Een na de wijziging gemaakte sleutel heeft ze wel.

Elke endpointpagina noemt de gecontroleerde machtiging, bijvoorbeeld organization.baremetal.deploy bij Besturingssysteem implementeren. Zeven bewerkingen controleren geen machtiging en zijn voor elke organisatiesleutel beschikbaar: lijsten en detailaanvragen van dedicated-server- en IP-blokconfiguraties, Regio's opvragen, Beschikbare rechten opvragen en SSH-sleutels opvragen. Elke andere bewerking controleert een van deze:

Machtiging	Bewerkingen
`organization.baremetal.read`	Alle leesaanvragen voor een server: details, status en voedingsstatus, bewerkingen, hardwaremetingen, bandbreedte, activiteit, netwerkpoorten, virtuele netwerken en installeerbare images en applicaties
`organization.baremetal.update`	Server hernoemen, opstartmodus en iPXE-script lezen of wijzigen
`organization.baremetal.deploy`	Besturingssysteem implementeren, hardwaretests uitvoeren en beide annuleren
`organization.baremetal.power`	Voedingsopdrachten en BMC-resets
`organization.baremetal.console`	Consolesessies en virtuele media
`organization.baremetal.networking`	Serversegmenten maken en verwijderen en servers met virtuele netwerken verbinden of loskoppelen
`organization.baremetal.lock`	Server vergrendelen en ontgrendelen
`organization.networking.read`	Virtuele netwerken, IP-blokken en adressen, VLAN-beschikbaarheid en beveiligingsscanresultaten lezen en een nieuwe scan inplannen
`organization.networking.virtual.manage`	Virtuele netwerken maken, hernoemen en verwijderen
`organization.networking.addresses.manage`	Adressen toewijzen, reserveren en vrijgeven en reverse DNS
`organization.billing.read`	Bestellingen, facturen en hun pdf's, abonnementen, gebruik en accounttegoed
`organization.billing.pay`	Facturen betalen, tegoed kopen en opgeslagen kaarten beheren
`organization.billing.orders.create`	Bestellingen en met uurfacturering aangemaakte servers en IP-blokken
`organization.billing.subscriptions.manage`	Abonnementen opzeggen en servers en IP-blokken verwijderen
`organization.assets.iso.read`	ISO-images opvragen in de bibliotheek en op een server
`organization.assets.iso.manage`	ISO-images uploaden en verwijderen
`organization.sshkeys.manage`	SSH-sleutels toevoegen, hernoemen en verwijderen
`organization.activity.read`	Activiteitenlog van de organisatie

Sleutels met minder machtigingen dan de Admin-rol kunnen niet worden gemaakt; een nieuwe sleutel heeft ze dus allemaal.

Een sleutel tot uw netwerken beperken

Een sleutel zonder toegestane netwerken werkt vanaf elk adres. Zodra er minstens één is ingesteld, wordt een aanvraag van buiten al die netwerken geweigerd alsof de sleutel onjuist is. Een vermelding is een enkel adres (198.51.100.7) of netwerk in CIDR-notatie (198.51.100.0/24), IPv4 of IPv6, ingesteld in de console. Een nieuwe sleutel accepteert maximaal 100 vermeldingen.

De API vergelijkt netwerken met het adres dat Cloudflare voor de verbinding meldt. Krijgt een beperkte sleutel een 401 in de aanvraagplayground, voer dezelfde aanvraag dan met cURL uit vanaf een toegestane machine.

Een sleutel uitschakelen

Uitschakelen in de console stopt een sleutel zonder de instellingen te verliezen; verwijderen wist hem definitief. Een uitgeschakelde, verwijderde of verlopen sleutel laat elke aanvraag op dezelfde manier mislukken als een onjuiste sleutel. De vervaldatum staat los van de aan/uit-schakelaar: het inschakelen van een verlopen sleutel maakt hem niet weer bruikbaar.

Authenticatiefouten

Status	`code`	Wanneer
`400`	`VALIDATION_ERROR`	De aanvraag verstuurt `X-API-KEY` samen met `Authorization` of een van beide dubbel. Het ene detail `INVALID_VALUE` noemt die header als `field` met `location` `header`.
`401`	`UNAUTHENTICATED`	Header ontbreekt; sleutel is onjuist, uitgeschakeld, verlopen of verwijderd; of de aanvraag komt van buiten de toegestane netwerken. De `message` is "Authentication is required or the supplied credentials are invalid."
`401`	`UNAUTHENTICATED`	De bewerking vereist een consolesessie (Bewerkingen die een sleutel niet kan aanroepen). De `message` vermeldt dit.
`403`	`NO_PERMISSION`	De sleutel is geldig maar mist de machtiging die het endpoint noemt.

Een sleutel die op beide manieren wordt verstuurd krijgt dit antwoord:

{
  "success": false,
  "data": null,
  "code": "VALIDATION_ERROR",
  "message": "X-API-KEY: Send one credential: the API key in the Authorization header or in X-API-KEY, not both.",
  "traceId": "SRV-1A2B-3C4D-5E6F-7A8B",
  "details": [
    {
      "code": "INVALID_VALUE",
      "message": "Send one credential: the API key in the Authorization header or in X-API-KEY, not both.",
      "field": "X-API-KEY",
      "location": "header"
    }
  ]
}

Beide 401-antwoorden bevatten WWW-Authenticate-headers met de toegestane toegangsbewijzen: Bearer en ApiKey header="X-API-KEY" waar een sleutel werkt, alleen Bearer bij consolebewerkingen, waar dit voor het consolesessietoken staat.

De eerste 401 noemt niet welke oorzaak van toepassing was. Controleer achtereenvolgens de sleutel zelf en of deze op Bearer volgt, de status onder Manage API Keys in de console en de toegestane netwerken.