The documentation is still WIP. Parts of it may sound really confusing or are not complete yet.

Apps

What are Apps?

An app can theoretically be anything that supports the HTTP protocol.
This can be a blog, forum, homepage, store, game, and many more.


What they all have in common:
They require an account for each person who'd like to fully use the page.


Implement Calucon Account into your app

First, you must create a new app under My Apps if you don't have one yet.


This requires you to specify a so-called Login-Url. Users that allow your application access to their username and email address will get redirected to this page.

This is where the HTTP protocol becomes important once we take a closer look at the HTTP-Packet that is sent to your login page:


HTTP Form Data:

ca_token = 050hH471IvbwVMS1D2xTqvXyMJY6uI9D

This is the "magic" behind our redirect which adds a field called ca_token to the POST data that is sent to your server.


To ensure maximum security you should always use HTTPS!
The reason for encoding the ca_token in the POST data is that others can't read it without breaking the encryption.
Not using HTTPS results in this data not being encrypted!

The value of ca_token in combination with your app token allows you to access the users' data.


Accessing the users' data

We provide a simple REST API that allows you to get the data in the JSON format.

To access the API, you always need your App Token. This token gets automatically generated when you create a new app. Once you go back to your app overview (My Apps), it is listed there among all other important information about your app.


API ENDPOINT: https://auth.calucon.de/api/
METHOD: userinfo
TYPE: POST

PARAMETERS: app = <YOUR_APP_TOKEN> user = <USER_TOKEN>

An example request using curl

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "app=<app_token>&user=<user_token>" https://auth.calucon.de/api/userinfo

Replace app_token and user_token with your own values.


Potential responses

App or User token being invalid:

null

User data access expired:

Once a user logs in, you have 24h to access their data. If you fail to do so, your access will expire. If the user logs in again, the timer will be reset and you have another 24h.

{
    "error": "Access denied -> User must log in again"
}

Success:

Congrats, you've done everything correct! In the JSON below is all user data that we are allowed to give to you. Use this to create a new user account if none exists yet.

{
    "username": "Calucon.DEV",
    "email": "simon@calucon.de"
}

Our Workflow recommendation

This is just a recommendation from our side. The implementation on your side is completely up to you.


1) Validate if received ca_token is already known to you

If the code is already known to you, you can log in the user with the associated user account.
If the code is not known to you, go on to the next step.


2) Request userdata

Make an HTTP call to our API as shown above using your app token for the app parameter and the ca_token for the user parameter.

You can then use the received data in combination with the ca_token to create a new user account.