## 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**

```bash
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**

```json
{
    "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
  ```python
  @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"
  ```