Platforms

IMPORTANT: The platform API is in early beta, there may still be some changes in the coming weeks.

To get access to the Zaikio Platform API, please contact us directly. The Platform API is for selected software vendors who have many apps and want to manage the apps themselves but still offer customers the flexibility of using a Zaikio account.

Becoming a platform member

To add a new customer to a Platform, a redirect flow must be performed using the Platform app and the scope directory.platform_membership.rw must be given. By adding prompt=signup the user will be prompted to the sign up (which is recommended).

https://hub.sandbox.zaikio.com/{PLATFORM_NAME}/oauth/authorize?client_id={PLATFORM_APP_CLIENT_ID}&redirect_uri={REDIRECT_URL}&scope=directory.platform_membership.rw&prompt=signup

If the customer does not have a Zaikio account, they can now fill out the whitelabel registration form and are automatically a member of the Platform. After that, further accesses can be made via the Platform API.

Another case is that the customer already has a Zaikio account, in which case the email would already be taken. Therefore, the customer still has the possibility to log in with an existing Zaikio account. In this case, the customer must additionally agree that the Platform receives permissions to their account.

Once the person is part of the Platform, new organizations can be created in their name via the Platform API, which are automatically also members of the Platform. The situation is different for already existing organizations (or organizations added later through Zaikio Hub or other apps). Here, the owners of the organizations must agree to the permissions. This is also done with the redirect flow:

https://hub.sandbox.zaikio.com/{PLATFORM_NAME}/oauth/authorize?client_id={PLATFORM_APP_CLIENT_ID}&redirect_uri={REDIRECT_URL}&scope=Org/a8911882-1fed-4d31-8ca4-4f75f2a44578.directory.platform_membership.rw

However, you can read what memberships the person has and display that in your platform to make the installation smooth.

Access the Platform API

Once people and organizations are part of your Platform, you can access their data through the Platform API.

For authorization, create a Private Access Token for the Platform owner organization (Organization > ... > Manage Private Access Tokens) with the scope directory.platform.rw. Make sure that you keep this JWT secret. It is also recommended to enable the "requires two-factor authentication" option for the organization in the production environment to increase security.

With this JWT you can now access the Zaikio Platform API.

Whitelabel Configuration & E-Mails

Coming soon

Means of Payment Redirect Flow

Since an organization's payment method can only be changed in Zaikio for integration and security reasons, there is a redirect flow for changing it. It takes the user back to a redirect URL after submitting or canceling the form. The user may have to log in. The page will appear in whitelabel style. The URL looks like this:

https://hub.sandbox.zaikio.com/{PLATFORM_NAME}/oauth/platform/means_of_payment?client_id={PLATFORM_APP_CLIENT_ID}&redirect_uri={REDIRECT_URL}&organization_id=a8911882-1fed-4d31-8ca4-4f75f2a44578

Password Change Redirect Flow

Since a password can only be changed in Zaikio for security reasons, there is a redirect flow for changing it. It takes the user back to a redirect URL after submitting or canceling the form. The user may have to log in. The URL looks like this:

https://hub.sandbox.zaikio.com/{PLATFORM_NAME}/oauth/platform/password?client_id={PLATFORM_APP_CLIENT_ID}&redirect_uri={REDIRECT_URL}

Email Change Redirect Flow

Since an email can only be changed in Zaikio for security reasons, there is a redirect flow for changing it. It takes the user back to a redirect URL after submitting or canceling the form. The user may have to log in. The URL looks like this:

https://hub.sandbox.zaikio.com/{PLATFORM_NAME}/oauth/platform/email?client_id={PLATFORM_APP_CLIENT_ID}&redirect_uri={REDIRECT_URL}