Authentifizierung

Allgemeines

Zur Authentifizierung verwenden wir OAuth2. Die benötigten Zugangsdaten erhältst du von uns.
Anwendungen werden über die ClientId und das ClientSecret identifiziert. Außerdem muss für deine Anwendung eine Redirect URI hinterlegt sein.

Verfügbare Grant Types

Authorization Code Grant

Aktuell ist nur der Authorization Code Grant verfügbar. Die Dokumentation bezieht sich also darauf.

Scopes

Scopes müssen mit Leerzeichen getrennt angegeben werden.

Erforderliche Scopes:

openid

receipts.write - muss wie folgt angegeben werden:
https://test.v.billless.dev/receipts.write 

Endpoints

/login

https://auth.billless.io/login

Der User wird über einen Browser auf diese Adresse weitergeleitet und gibt dort seine Zugangsdaten ein. Nach erfolgreichem Login, wird die angegebene Redirect URI mit dem Authorization Code aufgerufen. Mit dem Authorization Code können nun Access Token angefordert werden.

Request

GET https://auth.billless.io/login?
client_id=YOUR_CLIENT_ID
response_type=code&
scope=https://test.v.billless.dev/receipts.write openid&
redirect_uri=YOUR_REDIRECT_URI

Response

HTTP/1.1 302 Found
Location: https://YOUR_APP/redirect_uri?code=AUTHORIZATION_CODE&state=STATE

/token

https://auth.billless.io/token

Erforderliche Parameter im Header

Authorization: Basic Base64Encode(client_id:client_secret)

Content-Type: application/x-www-form-urlencoded

Access Token anfragen

Um ein Access Token anzufordern, wird der vorher erhaltene Authorization Code benötigt. Im Header müssen Client Id und Client Secret base64-codiert als Basic Authorization angegeben werden. Access Token haben eine Gültigkeit von einer Stunde. Refresh Token sind 30 Tage lang gültig.

Request

POST https://auth.billless.io/token&
Content-Type='application/x-www-form-urlencoded'&
Authorization=Basic aSdxd892iujendek328uedj...

grant_type=authorization_code&
client_id=YOUR_CLIENT_ID&
code=AUTHORIZATION_CODE&
redirect_uri=YOUR_REDIRECT_URI

Response

HTTP/1.1 200 OK
Content-Type: application/json

{ 
 "access_token":"eyJz9sdfsdfsdfsd...", 
 "refresh_token":"dn43ud8uj32nk2je...", 
 "id_token":"dmcxd329ujdmkemkd349r...",
 "token_type":"Bearer", 
 "expires_in":3600
}

Access Token mit Refresh Token erneuern

Mit dem Refresh Token kann ein abgelaufenes Access Token erneuert werden. Das geschieht über den selben Endpoint.

Request

POST https://auth.billless.io/token&
Content-Type='application/x-www-form-urlencoded'&
Authorization=Basic aSdxd892iujendek328uedj

grant_type=refresh_token&
client_id=YOUR_CLIENT_ID&
refresh_token=REFRESH_TOKEN

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
 "access_token":"eyJz9sdfsdfsdfsd", 
 "refresh_token":"dn43ud8uj32nk2je",
 "id_token":"dmcxd329ujdmkemkd349r",
 "token_type":"Bearer", 
 "expires_in":3600
}

/logout