OAuth Authentication
The xeebo API uses the OAuth 2.0 protocol for authentication and authorization. The API supports the OAuth 2.0 "Authorization Code Flow".
Start with register an app and get an API key and secret from the xeebo dev portal.
Point your user browser to the xeebo API login page. At the xeebo login page the user grants access and get redirected to your redirect url including an access code. Back at your application exchange the cceess code with an access token and a refresh token and store them for the authenticated user in our application for later use.
If the server needs to call the xeebo API, the access token can get used as long as the access token is not expired. If the token is expired, the refresh token can get used to get a new access token. This is possible in the background without user interaction.
For more information about OAuth 2.0 see the following websites:
Digitalocean
https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2
okta:
https://oauth.net/2/
Wikiedia:
https://de.wikipedia.org/wiki/OAuth
Get an API Key
Each application needs an API Key for access the xeebo API. Register your application and store the given API key and API Secret in a scure place. The API Key is used for identify your application if a users will authenticate and issue an access code. Your server must exchange a given access code and issue an access token and refresh token within a server to server call using the API Secret.
Important: The API Secret should never ever get exposed to your application users.
Get your API Key from the API Key page.
Authentication Code Flow
1. Implement the OAuth 2.0 "Authorization Code Flow" in your web application
by starting with a simple link pointing to our api login page using the following params:
client_id = <API Key, see xeebo dev portal>
response_type = code
scope = <scope comma separated without space>
redirect_uri = <your end point storing the redirected url params>
display = page
state = <a state token>
2. The user pointed to the xeebo API login page will get asked to accept the permission depending on the scope used in the url.
3. After login and accept the permission, the users browser will get redirected to your redirect url. The redirect url contains the following params where you must store in your app related to the user:
code=<authorization code for get an access_token>
state = <previous state given for approve and prevent cross site request forgery>
4. Your application must exchange the given authorization code within an access_token. Your application server must call the xeebo API in the background with a POST request and exchange the access code with the following data formated as json:
client_id = <API Key, see xeebo dev portal>
client_secret = <API Secret, see xeebo dev porta>
grant_type = authorization_code
code = <code extracted from rediect url>
5. The xeebo server repsonse contains the following body formated as json:
user = <user identity, xeebo nickname>
access_token = <authentication token used fo make API calls>
refresh_token = <token for exchange a new access_token if expired>
expires_in = <seconds after the access_token expires>
Extract and store the user, access_token, refresh_token and expires_in for the authenticated user in your application. The xeebo portal uses a unique nickname for each user. The user attribute given from the callback url is the xeebo nickname and must get used as the user identifier.
Make API calls
Make a xeebo API call using the access_token. Note: the access_token must get encoded with base64 in the request header as Authorization Bearer. e.g.
"Authorization": "Bearer <base64_encoded_access_token>"
Access token can expire. If the access token is expired, use the refresh token for issue an new valid access token. The server can make the api call and access token refresh call without any user interaction. This is usefull if your application have to make api calls in the background even if the user is not logged in.