Copy page

Entwickler

Authentifizierung bei der Public API

Ein Costfluent-API-Token mit genau den nötigen Berechtigungen erstellen, es mit jeder Anfrage senden und widerrufen.

Die Costfluent Public API akzeptiert Organisations-Token mit dem Präfix cf_org_ und Workspace-Token mit dem Präfix cf_ws_, jeweils gefolgt von 49 Buchstaben und Ziffern, deren letzte sechs eine Prüfsumme sind, an der Secret-Scanner ein echtes Token erkennen. Die Einstellungen erstellen beides: standardmäßig ein Organisations-Token, oder ein Workspace-Token, wenn Zugriff einen Arbeitsbereich nennt. Eine dritte Art im selben Format, mit dem Präfix cf_k8s_, ist ein Cluster-Token: Costfluent zeigt es, wenn ein Cluster unter Kubernetes angelegt wird, und es meldet die Nutzung dieses Clusters und sonst nichts (Kubernetes verbinden). Token sind Zugangsdaten: Speichern Sie sie nicht in Versionsverwaltung, Logs, Browser-Bundles oder geteilten Dokumenten.

Bevor Sie beginnen

Enthalten im Pro-, Business- und Custom-Tarif. Tarife vergleichen

• Ein Token erstellen erfordert die Organisationsrolle Eigentümer, Integrationsverantwortliche Person oder Bearbeiter, und ein Token kann nie eine Berechtigung tragen, die die erstellende Person nicht hat. Der Dialog zeigt nur die Berechtigungen, die Sie für den gewählten Zugriff vergeben dürfen. Ein Organisations-Token erreicht jeden Workspace, deshalb kann nur ein Eigentümer ihm eine Workspace-Berechtigung wie Kosten anzeigen geben; als Bearbeiter oder Integrationsverantwortliche Person wählen Sie stattdessen unter Zugriff einen Workspace, auf den Sie Zugriff haben, oder behalten Gesamte Organisation nur mit Organisationsberechtigungen. Ein Workspace-Token trägt nur Workspace-Berechtigungen.
• Ein Service-Token, das der Organisation gehört statt der Person, die es erstellt hat, kann nur ein Eigentümer erstellen, der Mitglied der Organisation ist.
• Ein Token, dessen einzige Berechtigung Kubernetes-Nutzung melden ist, lässt sich in jedem Tarif erstellen; das ist das Token, das der Kubernetes-Agent braucht. Auch dieses erfordert die Rolle Eigentümer, die als einzige diese Berechtigung hat.

Token erstellen

Die Vorlagen sind Ausgangsauswahlen, jeweils beschränkt auf das, was Sie für den gewählten Zugriff vergeben dürfen; eine Vorlage, die dort nichts anbietet, wird nicht gezeigt:

Die Berechtigungen sind gruppiert in Organisation und Arbeitsbereiche, Integrationen, Kosten und Anomalien, Budgets und Kostenwarnungen, Berichte und Dashboards, Zuordnung und Tags, Einsparungen, Benutzer, Teams und Kanäle und Kubernetes. Jede nennt, was sie erlaubt, etwa Kosten anzeigen oder Kostenwarnungen verwalten. Einsparungen verwalten erlaubt einem Token, Ansichten der Einsparungsliste zu speichern, zu ändern und zu löschen; die Potenziale selbst werden in der Konsole bearbeitet. Die API schreibt jede Berechtigung mit ihrer camelCase-Kennung, etwa viewCosts; so gibt /v1/me sie in capabilities zurück.

Token verwalten

API-Token listet jedes Token mit Name, Präfix, Berechtigungen, Erstellt von, wann es Erstellt und wann es Zuletzt verwendet wurde. Ein Token, dessen erstellende Person aus der Organisation entfernt, gesperrt oder erneut eingeladen wurde und noch nicht angenommen hat, wird dadurch nicht widerrufen, und seine Zeile zeigt Hat die Organisation verlassen: Ein Organisations- oder Workspace-Token funktioniert nicht mehr, bis die erstellende Person wieder aktives Mitglied ist, während das Cluster-Token des Kubernetes-Agents und ein Service-Token weiter funktionieren. Ein Workspace-Token, dessen erstellende Person noch Mitglied ist, in seinem Workspace aber nicht mehr alle seine Berechtigungen hat, zeigt Erstellende Person hat diesen Zugriff nicht mehr; was die Person dort nicht mehr darf, wird auch dem Token verweigert, und sobald sie den Zugriff zurückerhält, funktioniert es wieder vollständig. Widerrufen Sie es, wenn es endgültig nicht mehr gelten soll, und legen Sie für eine Integration, die weiterlaufen muss, ein Service-Token an. Die Liste sehen die Organisationsrollen Eigentümer, Integrationsverantwortliche Person und Bearbeiter, und ein Mitglied sieht nur die Workspace-Token der Workspaces, die es ansehen kann.

Um ein Token sofort zu beenden, öffnen Sie das Menü am Ende seiner Zeile, wählen Sie Token widerrufen und bestätigen Sie mit Widerrufen. Jede Anwendung, die es nutzt, verliert den Zugriff. Ein Eigentümer widerruft jedes Token; Bearbeiter und Integrationsverantwortliche Personen widerrufen die Token, die sie selbst erstellt haben, außer Service-Token, und nur deren Zeilen zeigen das Menü. Ein widerrufenes Token bleibt in der Liste, markiert mit Widerrufen.

Service-Token

Ein Service-Token gehört der Organisation statt der Person, die es erstellt hat. Seine Zeile zeigt Service-Token neben Erstellt von, und es funktioniert weiter, wenn diese Person die Organisation verlässt, gesperrt wird, kein Eigentümer mehr ist oder ihr Konto deaktiviert oder gelöscht wird: Nur die Berechtigungen, mit denen es erstellt wurde, sein Zugriff und der Tarif der Organisation begrenzen es. Was es schreibt, steht im Audit-Log mit dem Namen des Tokens als Akteur, wie bei jedem Token.

• Nur ein Eigentümer, der Mitglied der Organisation ist, erstellt eines; Mitarbeitende eines Partners in einer verwalteten Organisation können es nicht, denn das Token würde die Partnerschaft überdauern. Nur ein Eigentümer widerruft eines, unabhängig davon, wer es erstellt hat, sodass eine erstellende Person, die kein Eigentümer mehr ist, es nicht beenden kann.
• Es trägt nie mehr, als die erstellende Person beim Erstellen vergeben durfte: ein Service-Token für die Organisation jede Berechtigung im Dialog, eines für einen Workspace nur Workspace-Berechtigungen.
• Seine Zeile nennt weiter die erstellende Person und zeigt Hat die Organisation verlassen, sobald sie geht. Diese Person hat seinen Wert beim Erstellen gesehen; erstellen Sie deshalb, wenn sie geht, ein neues Service-Token, stellen Sie die Integration darauf um und widerrufen Sie das alte.

Anfrage senden

Übergeben Sie das Token mit dem standardmäßigen Bearer-Autorisierungsschema:

Code
curl --request GET \
  --url https://api.costfluent.com/v1/cost-reports \
  --header "Authorization: Bearer $COSTFLUENT_API_TOKEN"

Verwenden Sie Ihre Token nur mit https://api.costfluent.com.

Playground sicher verwenden

Die API-Referenz enthält einen interaktiven Playground. Wählen Sie den richtigen Server, autorisieren Sie sich mit einem eingeschränkten Token und prüfen Sie die Anfrage vor dem Senden. Schreib- und Löschoperationen verändern Workspace-Daten auf dem ausgewählten Server.

Workspace-Token

Ein Workspace-Token handelt in seinem eigenen Workspace so, wie ein Organisations-Token in jedem Workspace handelt, und nirgends sonst:

Wie es sich verhält

• Eine Anfrage wird abgelehnt, wenn dem Token die Berechtigung fehlt, die der Vorgang braucht, unabhängig von der Rolle der Person, die es erstellt hat. Die API-Referenz nennt diese Berechtigung bei jedem Vorgang, auf Englisch, etwa "Needs an organization token with inviteUser", und die Antwort 403 nennt sie in errors[0] mit dem Code missing_capability.
• Ein Token läuft spätestens ein Jahr nach seiner Erstellung ab. Eine Anfrage an die Backend API ohne Ablaufdatum erhält 90 Tage; eine mit einem Datum mehr als ein Jahr entfernt wird mit 400 abgelehnt, und eine mit neverExpires mit 403, außer ein Eigentümer sendet sie.
• Ein Token funktioniert nicht mehr und antwortet mit 401, sobald das Konto, das es erstellt hat, deaktiviert oder gelöscht ist. Ein Organisations- oder Workspace-Token antwortet außerdem mit 401, solange die erstellende Person kein aktives Mitglied der Organisation ist, und funktioniert wieder, wenn sie reaktiviert wird; das Cluster-Token des Kubernetes-Agents funktioniert weiter, wie Token verwalten beschreibt. Ein Service-Token beendet keine der beiden Regeln: Nur sein Widerruf, sein Ablauf oder das Löschen seines Workspaces beendet es.
• Ein Organisations- oder Workspace-Token zu erstellen erfordert eine aktuelle Anmeldung: eine Anmeldung oder eine Bestätigung, dass Sie es sind, aus den letzten 60 Minuten. Aus einer älteren Sitzung antwortet die Anfrage mit 403 und reauthentication_required, und die Konsole bittet Sie zu bestätigen, dass Sie es sind, und erstellt dann das Token; eine aufgefrischte Sitzung zählt nicht.
• Ein 401 trägt WWW-Authenticate: Bearer realm="costfluent", error="invalid_token", wenn ein Token gesendet wurde, und nur den Realm, wenn keines gesendet wurde.
• Enthält der Tarif der Organisation keine API-Tokens, antwortet jede Anfrage mit einem ihrer Tokens mit 403 und plan_upgrade_required, und errors[0] nennt den Tarif, der sie enthält. Nach einem Upgrade funktionieren die Tokens wieder. Ein Organisations-Token, das nur Kubernetes-Nutzung melden trägt, funktioniert in jedem Tarif weiter. Ein widerrufenes oder abgelaufenes Token oder ein Workspace-Token, dessen Workspace gelöscht wurde, antwortet zuerst mit 401.
• Der Dialog bietet nur an, was Sie für den gewählten Zugriff vergeben dürfen, und beim Wechsel des Zugriffs bleiben nur die Berechtigungen ausgewählt, die auch dieser anbietet. Eine Anfrage an die Backend-API, die mehr verlangt, wird mit 403 abgelehnt und nennt die Berechtigungen. Eine Anfrage für ein Workspace-Token behält nur ihre Workspace-Berechtigungen; eine ohne solche wird abgelehnt.
• Ein Organisations-Token, das ein Bearbeiter oder eine Integrationsverantwortliche Person erstellt hat, bevor nur Eigentümer ihm Workspace-Berechtigungen geben konnten, erreicht nur die Workspaces, auf die die erstellende Person Zugriff hat, und dort nicht mehr, als sie hat; jeder andere Workspace antwortet mit 403. Seine Organisationsberechtigungen funktionieren weiter. Ein Token, das ein Eigentümer erstellt hat, erreicht jeden Workspace, solange diese Person Eigentümer bleibt, und eine Organisationsberechtigung, die nur Eigentümer haben, etwa Arbeitsbereiche bearbeiten, Arbeitsbereiche löschen oder Teams verwalten, funktioniert nur, solange die erstellende Person sie noch hat, und /v1/me lässt sie so lange in capabilities aus, wie auch eine Workspace-Berechtigung, die die erstellende Person in keinem Workspace hat. Kubernetes-Nutzung melden ist die Ausnahme: Der Agent meldet weiter, bis das Token widerrufen wird. Ein so abgelehntes 403 sagt in detail, dass die erstellende Person die Berechtigung nicht hat, und nennt in errors keine, denn ein neues Token derselben Person würde genauso abgelehnt.
• Ein Workspace-Token darf in seinem Workspace nie mehr, als die erstellende Person dort gerade darf. Verliert sie den Zugriff auf den Workspace oder hat sie dort weniger Rechte, etwa Kann ansehen statt Kann bearbeiten, lehnt die API für das Token alles, was die Person nicht mehr darf, mit demselben 403 ab, eine Liste ohne angegebenen Workspace lässt ihn aus, sobald die Person ihn nicht mehr sehen kann, und /v1/me führt diese Berechtigungen nicht mehr in capabilities. Erhält sie den Zugriff zurück, funktioniert das Token wieder vollständig. Ein Workspace-Token, das ein Eigentümer erstellt hat, behält alle seine Berechtigungen, solange diese Person Eigentümer bleibt.
• Für ein Service-Token gilt keine der beiden Regeln oben: Es behält jede Berechtigung, mit der es erstellt wurde, in jedem Workspace, den sein Zugriff erreicht, unabhängig davon, was die erstellende Person heute darf.
• Wird workspaceId bei /v1/costs oder /v1/costs/summary angegeben, beschränken sich die Zahlen auf die Integrationen, die mit diesem Workspace verknüpft sind, auch für ein Organisations-Token.
• Ein Objekt einer anderen Organisation antwortet jedem Token mit 404.
• /v1/me nennt defaultWorkspaceId, den Workspace, in dem gearbeitet wird, wenn keiner angegeben ist: bei einem Workspace-Token dessen eigenen; bei einem Organisations-Token den Standard-Workspace der Person, die es erstellt hat, solange sie aktives Mitglied ist und ihn sehen darf, sonst den ältesten Workspace, den das Token erreicht. Ein Service-Token nennt immer den ältesten Workspace, den es erreicht, sodass sich sein Standard nicht ändert, wenn die erstellende Person geht oder einen anderen wählt.

Verwandte Seiten

• Terraform
• API-Referenz
• Kubernetes verbinden