DocumentationDeveloperAcademyCommunitySupportLogin

LumApps Access Requirements

Suggest Edits

Why do we need access to your LumApps instance?

Our knowledge fetcher gets the content stored in your LumApps instance utilising the available API’s and performs the “snippetization” process to cache relevant article data with relevant tags.

How to authenticate LumApps with a service account ?

To authenticate with LumApps we use the service account created within the customer’s instance:

Create and authorize credentials

In APIs & Services > Credentials click create credentials > Service account and follow the steps. During the last step, generate a key and get the client ID inside it.

Lastly, send an email to [email protected], specify:

  • you want to use LumApps delegation.
  • the clientID (xxxxxxxxxxxxxxxxxxxxx) to be granted access.
  • the customer ID on which to grant access.
  • the environment of the customer.

This will allow the service account to generate token for the target customer’s LumApps instance and fetch knowledge contents.

To generate a bearer token with this account we need to run a python script which takes inputs from the service_account.json file.

Service account details

{
  "type": "service_account",
  "project_id": "",
  "private_key_id": "",
  "private_key": "",
  "client_email": "",
  "client_id": "",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/{client_email value}"
}

The fields which are empty need input from the customer in the service_account.json file

Token generation script

import requests
import datetime
import json
import jwt

 
MY_LUMAPPS_ENV = "https://sites.lumapps.com"
LUMAPPS_API_BASE_URL = f"{MY_LUMAPPS_ENV}/_ah/api/lumsites/v1"

def call_lumapps_apis_with_service_account_raw():
    #
    #  1 - Construct a jwt with your service account
    #
    with open("service _account.json", "r") as f:
        service_account = json.load(f)

    sa_email = service_account["client_email"]
    sa_private_key = service_account["private_key"]
    current_timestamp = datetime.datetime.now().timestamp()
    exp_time = current_timestamp + 30 
    data = {
        'aud': 'https://www.googleapis.com/oauth2/v4/token',
        'iss': sa_email,
        'iat': current_timestamp,
        'exp': exp_time,           # expiry time is 30 seconds from time of creation
        'scope': 'https://www.googleapis.com/auth/userinfo.email'
    }
    constructed_jwt = jwt.encode(data, sa_private_key, algorithm='RS256')
    print(f"constructed_jwt={constructed_jwt}")

    # 
    # 2 - Get a google token from your jwt
    #
    google_token_url = "https://www.googleapis.com/oauth2/v4/token"
    body = {
        "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
        "assertion": constructed_jwt
    }
    response = requests.post(google_token_url, data=body)
    response.raise_for_status()
    response_json = response.json()
    google_token = response_json["access_token"]

    #
    #  3 - Call LumApps api "user/getToken" endpoint with your google token
    # to get a LumApps jwt token authenticated as a user.
    #
    url = f"{LUMAPPS_API_BASE_URL}/user/getToken"
    headers = {"Authorization": f"Bearer {google_token}"}
    customer_id = ""              # Your customer id
    user_to_authenticate_as = ""  # The email of the user you want to authenticate as
    params = {
        "customerId": customer_id,
        "email": user_to_authenticate_as
    }

    response = requests.get(url, params=params, headers=headers)
    response.raise_for_status()
    response_json = response.json()
    lumapps_token = response_json["accessToken"]

    # 
    # 4 - Call a lumapps endpoints using the access token you just retrieved
    # 

    # Here we call user/get to get the user associated to the token
    # See https://apiv1.lumapps.com for more informations about other endpoints

    url = f"{LUMAPPS_API_BASE_URL}/user/get" # user/get endpoint
    headers = {"Authorization": f"Bearer {lumapps_token}"}
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    user = response.json()
    print(f"User: {user}")

token generation script

import requests
import datetime
import json
import jwt

 
MY_LUMAPPS_ENV = "https://sites.lumapps.com"
LUMAPPS_API_BASE_URL = f"{MY_LUMAPPS_ENV}/_ah/api/lumsites/v1"


def call_lumapps_apis_with_service_account_raw():
    #
    #  1 - Construct a jwt with your service account
    #
    with open("service _account.json", "r") as f:
        service_account = json.load(f)

    sa_email = service_account["client_email"]
    sa_private_key = service_account["private_key"]
    current_timestamp = datetime.datetime.now().timestamp()
    exp_time = current_timestamp + 30 
    data = {
        'aud': 'https://www.googleapis.com/oauth2/v4/token',
        'iss': sa_email,
        'iat': current_timestamp,
        'exp': exp_time,           # expiry time is 30 seconds from time of creation
        'scope': 'https://www.googleapis.com/auth/userinfo.email'
    }
    constructed_jwt = jwt.encode(data, sa_private_key, algorithm='RS256')
    print(f"constructed_jwt={constructed_jwt}")


    # 
    # 2 - Get a google token from your jwt
    #
    google_token_url = "https://www.googleapis.com/oauth2/v4/token"
    body = {
        "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
        "assertion": constructed_jwt
    }
    response = requests.post(google_token_url, data=body)
    response.raise_for_status()
    response_json = response.json()
    google_token = response_json["access_token"]


    #
    #  3 - Call LumApps api "user/getToken" endpoint with your google token
    # to get a LumApps jwt token authenticated as a user.
    #
    url = f"{LUMAPPS_API_BASE_URL}/user/getToken"
    headers = {"Authorization": f"Bearer {google_token}"}
    customer_id = ""              # Your customer id
    user_to_authenticate_as = ""  # The email of the user you want to authenticate as
    params = {
        "customerId": customer_id,
        "email": user_to_authenticate_as
    }

    response = requests.get(url, params=params, headers=headers)
    response.raise_for_status()
    response_json = response.json()
    lumapps_token = response_json["accessToken"]


    # 
    # 4 - Call a lumapps endpoints using the access token you just retrieved
    # 

    # Here we call user/get to get the user associated to the token
    # See https://apiv1.lumapps.com for more informations about other endpoints

    url = f"{LUMAPPS_API_BASE_URL}/user/get" # user/get endpoint
    headers = {"Authorization": f"Bearer {lumapps_token}"}
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    user = response.json()
    print(f"User: {user}")

Updated 5 months ago