NAV Navbar
cURL

BANKSapi Auth API

Wenn Sie sich mehr für die Kundendaten interessieren, möchten wir Ihnen unsere Schnellstartanleitung nahe legen.

Die BANKSapi Auth API stellt Funktionen zur Verwaltung von Benutzern bereit. Über das OAuth2-Protokoll erzeugen Sie Tokens, mit denen nur die Funktionen freigeschalten werden, die für den jeweiligen Anwendungsfall notwendig sind.

Die API ist vom Aufbau her mit den anderen BANKSapi Banks/Connect APIs vergleichbar. Das bedeutet vor allem auch, dass für diese API alles im Banks/Connect API Überblick Geschriebene gilt.

Die Nutzung dieser API ist eine grundlegende Voraussetzung für die Anbindung aller von BANKSapi angebotenen APIs.

Management-API-Referenz

Client-Zugänge

Wenn Sie unser Mandant werden, erhalten Sie einen Client-Zugang für Administrative Zwecke (im Folgenden Admin-Client) sowie einen Client-Zugang für die durch Sie erstellte Anwendung (im Folgenden User-Client).

Die meisten Funktionen dieser Management-API sind nur für den Admin-Client verfügbar. Ausnahmen sind am jeweiligen Anwendungsfall hervorgehoben.

Die konkrete Ausgestaltung der Auth-API wird in gemeinsamer Abstimmung mit dem Support vorgenommen.

Scope

Ein Scope benennt eine Klasse von Zugriffsrechen. Es handelt sich um einen String, meist in Form einer (fiktiven) URL. Die verfügbaren Scopes sind abhängig vom gebuchten Leistungsumfang. Sie erhalten die Scope-Liste daher zusammen mit Ihrem Kooperationsvertrag.

Tenant

{
   "name":"demo",
   "description":"Ein Tenant für Demonstrationszwecke"
}

Das Tenant-Objekt stellt unseren Mandanten dar. Es spielt für die Nutzung der API nur insofern eine Rolle, dass der Tenant-Name ein URL-Bestanteil in der Management-API ist.

Feld Typ Vorhanden Beschreibung
name String Immer Technischer Name des Tenant, wird URL-Bestandteil
description String Optional Optionale menschenlesbare Beschreibung

Tenants abrufen

# Dieser Aufruf ist nur ein Beispiel und mit dem Demo-Account nicht nutzbar
$ curl https://banksapi.io/auth/mgmt/v1/tenants \
    -X GET \
    -H 'Expect: ' \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'accept: application/json'

Mit dieser Funktion lassen sich alle Tenants abrufen.

HTTP-Methode
GET
Gültigkeit
Dauerhaft bis EOL API-Version 1.X
OAuth2-Scope
auth/tenants/read

Rückgabe

Im Erfolgsfall kommt ein Array von Tenant zurück.

Tenant abrufen

# Dieser Aufruf ist nur ein Beispiel und mit dem Demo-Account nicht nutzbar
$ curl https://banksapi.io/auth/mgmt/v1/tenants/demo \
    -X GET \
    -H 'Expect: ' \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'accept: application/json'

Mit dieser Funktion lässt sich ein einzelner Tenant abrufen.

HTTP-Methode
GET
Gültigkeit
Dauerhaft bis Status 410
OAuth2-Scope
auth/tenants/read

Rückgabe

Im Erfolgsfall kommt ein Tenant zurück.

Client

{
   "name":"demo-client",
   "username":"demo/demo-client",
   "description":"Ein Client für Demonstrationszwecke",
   "grantedScopes":[
      "http://banksapi.io/provider/read",
      "http://banksapi.io/customer/read"
   ]
}

Ein Client ist eine Software, welche BANKSapi-Leistungen aufruft. Im standard bekommt jeder Mandant einen User-Client für die im Rahmen der Geschäftstätigkeit genutzten Funktionsumfang und einen Admin-Client für die Anbindung der Backoffice-Prozesse.

Feld Typ Vorhanden Beschreibung
name String Immer Technischer Name für den Client, wird als URL verwendet
username String Immer Username für den Client zum Bezug eines OAuth2-Tokens
description String Wenn vorhanden Menschenlesbare Beschreibung des Clients
grantedScopes Array von String Wenn vorhanden Liste der maximal für den Client zuweisbaren Scopes

Clients abrufen

# Dieser Aufruf ist nur ein Beispiel und mit dem Demo-Account nicht nutzbar
$ curl https://banksapi.io/auth/mgmt/v1/tenants/demo/clients \
    -X GET \
    -H 'Expect: ' \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'accept: application/json'

Mit dieser Funktion lassen sich alle Clients abrufen.

HTTP-Methode
GET
Gültigkeit
Dauerhaft bis Status 410
OAuth2-Scope
auth/tenants/clients/read

Rückgabe

Im Erfolgsfall kommt ein Array von Clients zurück.

Client abrufen

# Dieser Aufruf ist nur ein Beispiel und mit dem Demo-Account nicht nutzbar
$ curl https://banksapi.io/auth/mgmt/v1/tenants/demo/clients/demo-client \
    -X GET \
    -H 'Expect: ' \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'accept: application/json'

Mit dieser Funktion lässt sich ein einzelner Client abrufen.

HTTP-Methode
GET
Gültigkeit
Dauerhaft bis Status 410
OAuth2-Scope
auth/tenants/clients/read

Rückgabe

Im Erfolgsfall kommt ein Client zurück.

ClientRole

{
   "name":"demo-role",
   "description":"Eine Rolle zu Präsentationszwecken",
   "defaultRole":true,
   "grantedScopes":[
       "http://banksapi.io/customer/read",
       "http://banksapi.io/customer/modify"
   ]
}

Eine ClientRole ist eine Gruppe von Usern und Scopes innerhalb eines Clients.

Feld Typ Vorhanden Beschreibung
name String Immer Technischer Name für die ClientRole, wird als URL verwendet
description String Wenn vorhanden Menschenlesbare Beschreibung des Clients
defaultRole Boolean Immer Gibt an ob die Rolle bei durch den Client neu angelegten Benutzern automatisch zugewiesen wird
grantedScopes Array von String Wenn vorhanden Liste der zugewiesenen Scopes

ClientRoles abrufen

# Dieser Aufruf ist nur ein Beispiel und mit dem Demo-Account nicht nutzbar
$ curl https://banksapi.io/auth/mgmt/v1/tenants/demo/clients/demo-client/roles \
    -X GET \
    -H 'Expect: ' \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'accept: application/json'

Mit dieser Funktion lassen sich alle ClientRoles abrufen.

HTTP-Methode
GET
Gültigkeit
Dauerhaft bis Status 410
OAuth2-Scope
auth/tenants/clients/read

Rückgabe

Im Erfolgsfall kommt ein Array von ClientRoles zurück.

ClientRole abrufen

# Dieser Aufruf ist nur ein Beispiel und mit dem Demo-Account nicht nutzbar
$ curl https://banksapi.io/auth/mgmt/v1/tenants/demo/clients/demo-client/roles/demo-role \
    -X GET \
    -H 'Expect: ' \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'accept: application/json'

Mit dieser Funktion lässt sich eine einzelne ClientRole abrufen.

HTTP-Methode
GET
Gültigkeit
Dauerhaft bis Status 410
OAuth2-Scope
auth/tenants/clients/read

Rückgabe

Im Erfolgsfall kommt eine ClientRole zurück.

ClientRole Users abrufen

# Dieser Aufruf ist nur ein Beispiel und mit dem Demo-Account nicht nutzbar
$ curl https://banksapi.io/auth/mgmt/v1/tenants/demo/clients/demo-client/roles/demo-role/users \
    -X GET \
    -H 'Expect: ' \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'accept: application/json'

Mit dieser Funktion lässt sich eine Liste der der ClientRole zugewiesenen Benutzer(-Referenzen) abrufen.

HTTP-Methode
GET
Gültigkeit
Dauerhaft bis Status 410
OAuth2-Scope
auth/tenants/clients/read

Rückgabe

Im Erfolgsfall kommt ein Array von User-Referenzen zurück.

ClientRole User hinzufügen

# Dieser Aufruf ist nur ein Beispiel und mit dem Demo-Account nicht nutzbar
$ curl https://banksapi.io/auth/mgmt/v1/tenants/demo/clients/demo-client/roles/demo-role/users \
    -X POST \
    -H 'Expect: ' \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'accept: application/json'

Mit dieser Funktion lässt sich ein Benutzer zu einer ClientRole hinzufügen.

HTTP-Methode
POST
Gültigkeit
Dauerhaft bis Status 410
OAuth2-Scope
auth/tenants/clients/roles/assign

Request-Body

"1c5b33f6-9c4d-11e6-ba80-480fcfb9550f"

Rückgabe

Im Erfolgsfall kommt der HTTP-Status 201 (Created) mit einem Location-Header zurück, unter der die ClientRole-User abgerufen werden kann.

ClientRole User abrufen

# Dieser Aufruf ist nur ein Beispiel und mit dem Demo-Account nicht nutzbar
$ curl https://banksapi.io/auth/mgmt/v1/tenants/demo/clients/demo-client/roles/demo-role/users/1c5b33f6-9c4d-11e6-ba80-480fcfb9550f \
    -X GET \
    -H 'Expect: ' \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'accept: application/json'

Mit dieser Funktion lässt sich eine der ClientRole zugewiesene User-Referenzen abrufen.

HTTP-Methode
GET
Gültigkeit
Dauerhaft bis Status 410
OAuth2-Scope
auth/tenants/clients/read

Rückgabe

{
   "userReference":"1c5b33f6-9c4d-11e6-ba80-480fcfb9550f"
}

Im Erfolgsfall kommt eine User-Reference zurück.

User

{
   "userReference":"1c5b33f6-9c4d-11e6-ba80-480fcfb9550f",
   "username":"demo-user"
}

Dieses Objekt stellt einen eindeutigen Benutzer dar.

Feld Typ Vorhanden Beschreibung
userReference String Immer Technischer ID für den User, wird auch in URLs verwendet.
username String Immer Username zur Erstellung eines OAuth2-Tokens

Users abrufen

# Dieser Aufruf ist nur ein Beispiel und mit dem Demo-Account nicht nutzbar
$ curl https://banksapi.io/auth/mgmt/v1/tenants/demo/users \
    -X GET \
    -H 'Expect: ' \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'accept: application/json'

Mit dieser Funktion lassen sich alle aktivierten Users abrufen.

HTTP-Methode
GET
Gültigkeit
Dauerhaft bis Status 410
OAuth2-Scope
auth/tenants/users/read

Rückgabe

Im Erfolgsfall kommt ein Array von Users zurück.

User abrufen

# Dieser Aufruf ist nur ein Beispiel und mit dem Demo-Account nicht nutzbar
$ curl https://banksapi.io/auth/mgmt/v1/tenants/demo/users/1c5b33f6-9c4d-11e6-ba80-480fcfb9550f \
    -X GET \
    -H 'Expect: ' \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'accept: application/json'

Mit dieser Funktion lässt sich ein einzelner aktivierter User abrufen.

HTTP-Methode
GET
Gültigkeit
Dauerhaft bis Status 410
OAuth2-Scope
auth/tenants/users/read

Rückgabe

Im Erfolgsfall kommt ein User zurück.

User anlegen

# Dieser Aufruf ist nur ein Beispiel und mit dem Demo-Account nicht nutzbar
$ curl https://banksapi.io/auth/mgmt/v1/tenants/demo/users \
    -X POST \
    -H 'Expect: ' \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'accept: application/json' \
    -H 'content-type: application/json'

Mit dieser Funktion lässt sich ein User erzeugen. Nach dem Erzeugen ist er automatisch aktiviert.

HTTP-Methode
POST
Gültigkeit
Dauerhaft bis Status 410
OAuth2-Scope
auth/tenants/users/create

Request-Body

{
    "username":"demo-user",
    "password":"secret",
    "firstname":"demo",
    "lastname":"user"
}
Feld Typ Pflichtfeld Beschreibung
username String Ja Der eindeutige Benutzername
password String Ja Das Passwort
firstname String Nein Der Vorname
lastname String Nein Der Nachname

Rückgabe

Im Erfolgsfall kommt der HTTP-Status 201 (Created) mit einem Location-Header zurück, unter der der User abrufen werden kann.

User deaktivieren

# Dieser Aufruf ist nur ein Beispiel und mit dem Demo-Account nicht nutzbar
$ curl https://banksapi.io/auth/mgmt/v1/tenants/demo/users/1c5b33f6-9c4d-11e6-ba80-480fcfb9550f/deactivate \
    -X GET \
    -H 'Expect: ' \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'accept: application/json'

Mit dieser Funktion lässt sich ein einzelner User deaktivieren.

HTTP-Methode
PUT
Gültigkeit
Dauerhaft bis Status 410
OAuth2-Scope
auth/tenants/users/create

Rückgabe

Im Erfolgsfall kommt ein HTTP-Status 200 (OK)

User reaktivieren

# Dieser Aufruf ist nur ein Beispiel und mit dem Demo-Account nicht nutzbar
$ curl https://banksapi.io/auth/mgmt/v1/tenants/demo/users/1c5b33f6-9c4d-11e6-ba80-480fcfb9550f/reactivate \
    -X GET \
    -H 'Expect: ' \
    -H 'authorization: bearer 0defaced-1337-d00d-c0de-face8badcafe' \
    -H 'accept: application/json'

Mit dieser Funktion lässt sich ein einzelner deaktivierter User reaktivieren.

HTTP-Methode
POST
Gültigkeit
Dauerhaft bis Status 410
OAuth2-Scope
auth/tenants/users/create

Request-Body

{
    "username":"demo-user",
    "password":"secret",
    "firstname":"demo",
    "lastname":"user"
}
Feld Typ Pflichtfeld Beschreibung
username String Ja Der eindeutige Benutzername
password String Ja Das Passwort
firstname String Nein Der Vorname
lastname String Nein Der Nachname

Rückgabe

Im Erfolgsfall kommt ein HTTP-Status 200 (OK)

OAuth2-API-Referenz

Dieser Abschnitt beschreibt die OAuth2-Implementierung in der BANKSapi Auth API. Für tiefergehende Informationen über OAuth2 sei auf die einschlägige Literatur sowie die Spezifikation verwiesen.

Token

{
  "scope":"http://banksapi.io/customer/read http://banksapi.io/customer/modify",
  "tenant":"demo",
  "client":"demo-client",
  "user":"1c5b33f6-9c4d-11e6-ba80-480fcfb9550f",
  "access_token":"0defaced-1337-d00d-c0de-face8badcafe",
  "token_type":"Bearer"
}
Feld Typ Vorhanden Beschreibung
scope String Immer Leerzeichen-getrennte Liste von OAuth2-Scopes
tenant String Immer Technischer Name des Tenant
client String Immer Technischer Name des Client
user String Wenn User-Token User-Referenz
access_token String Immer Der Token
token_type String Immer Immer "Bearer"

Der OAuth2-Token ist grundsätzlich ein String, der in der Kommunikation zwischen unseren Services sowie Ihnen herumgereicht wird, und an dem bestimmte Berechtigungen hängen.

Client-Token anfordern

Ein Client-Token ist ein unpersonalisiertes Token. Mit ihm lassen sich einige ausgewählte Anwendungsfälle durchführen.

Aufruf

$ curl https://banksapi.io/auth/oauth2/token \
    -X POST \
    -H 'Expect: ' \
    -H 'authorization: basic ZGVtby9iYW5rc2FwaTpkZW1v' \
    -H 'content-type: application/x-www-form-urlencoded' \
    -d 'grant_type=client_credentials&scope=http://banksapi.io/provider/read'

Der Client-Token wird über einen POST-Request an die URL https://banksapi.io/auth/oauth2/token angefordert.

Request-Body

Der Request-Body ist ein POST-Formular mit den folgenden Parametern:

Feld Typ Pflichtfeld Beschreibung
grant_type String Ja Muss immer client_credentials lauten
scope String Nein Leerzeichen-getrennte Liste von gewünschten Scopes

Rückgabe

Im Erfolgsfall kommt ein Token zurück. Bei Anmeldefehler kommt der HTTP-Status 401.

User-Token anfordern

$ curl https://banksapi.io/auth/oauth2/token \
    -X POST \
    -H 'Expect: ' \
    -H 'authorization: basic ZGVtby9iYW5rc2FwaTpkZW1v' \
    -H 'content-type: application/x-www-form-urlencoded' \
    -d 'grant_type=password&username=demo&password=demo&scope=http://banksapi.io/provider/read'

Der User-Token wird über einen POST-Request an die URL https://banksapi.io/auth/oauth2/token angefordert.

Request-Body

Der Request-Body ist ein POST-Formular mit den folgenden Parametern:

Feld Typ Pflichtfeld Beschreibung
grant_type String Ja Muss immer password lauten
username String Ja Der Benutzername
password String Ja das Passwort
scope String Nein Leerzeichen-getrennte Liste von gewünschten Scopes

Rückgabe

Im Erfolgsfall kommt ein Token zurück. Bei Anmeldefehler kommt der HTTP-Status 401.

Token zurückziehen

$ curl https://banksapi.io/auth/oauth2/revoke \
    -X POST \
    -H 'Expect: ' \
    -H 'authorization: basic ZGVtby9iYW5rc2FwaTpkZW1v' \
    -H 'content-type: application/x-www-form-urlencoded' \
    -d 'token=0defaced-1337-d00d-c0de-face8badcafe'

Der User-Token wird über einen POST-Request an die URL https://banksapi.io/auth/oauth2/revoke geschickt.

Request-Body

Der Request-Body ist ein POST-Formular mit den folgenden Parametern:

Feld Typ Pflichtfeld Beschreibung
token String Ja Der Token, der zurückgezogen werden soll

Rückgabe

Es kommt immer der HTTP-Status 200 zurück.

Changelog

Version 1.0