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