jcloude/press/saas/api/readme.md

Jcloude SaaS API

These APIs has been introduced with the release of SaaS v2. It will provide a interface to communicate back to Jingrow Cloud from deployed site.

Authentication using secret token

In Site configuration, the authentication token will be provided - fc_communication_secret

For any kind of requests, from client-end, we need to set the credentials in header

X-Site: example.erpnext.com
X-Site-Token: 319f41d07d430ed77df3d41a82787f4edff1440f12e43784a7ce8b4e

All the api functions are wrapped in jingrow.whitelist(allow_guest=True) . However, due to the custom authentication wrapper, guest can't access the endpoints

Authentication using access token

Why ?

Sometimes, we may need to pass the secret token to frontend for some specific tasks (example - in-desk checkout). In those case, instead of using our authentication secret token, we can generate a temporary access token from jingrow cloud and use that for the session.

Note: Generated access tokens are valid for 15 minutes.

Generate Access Token

Request

curl --location --request POST 'http://fc.local:8000/api/method/jcloude.saas.api.auth.generate_access_token' \
--header 'x-site: oka-hdz-qpj.tanmoy.fc.jingrow.dev' \
--header 'x-site-token: 004f85a3ae93927d2f0fcc668d11cb71'

Response

{
    "message": "fbk23eva6k:3e2882eff23d4145ddfefaebf5ac6135"
}

After we generated our access token, set this specific header to any saas api requests to jingrow cloud.

X-Site-Access-Token: fbk23eva6k:3e2882eff23d4145ddfefaebf5ac6135

Usage Guide

• In jcloude.saas.api __init__ file, there is a decorator @whitelist_saas_api which can be used to convert the functions to api
• @whitelist_saas_api also set the site's team's user as current session user to make the session properly authenticated.
• @whitelist_saas_api also add couple of variable and functions to jingrow.local.

  Type	Name	Description
  Variable	jingrow.local.site_name	Site name
  Variable	jingrow.local.team_name	Current team name
  Function	jingrow.local.get_site() -> Site	Fetch current site pagetype record
  Function	jingrow.local.get_team() -> Team	Fetch current team pagetype record
  Variable (Additional)	jingrow.session.user	Logged in user name, This will be also available as we have set team.user to logged in user

• Sample Code

  @whitelist_saas_api
  def hello():
      print(jingrow.local.site_name)
      print(jingrow.local.get_site())
      print(jingrow.local.team_name)
      print(jingrow.local.get_team())
      return f"👋 Hi! {jingrow.local.site_name} is authenticated"