community api

You have 4 authentication options when using Postman to authenticate with the API

1. Session Key (local account username and password)
2. Bearer token using SDK Key
3. Access Token using pre-shared key (Dev Tools API apps)
4. OAuth Grant Flow (Community SSO)

 

Option #1 is the easiest/best option, and what I use most commonly. This means you would login with an account created locally on the community (not using SSO). In the latest version of Aurora (24.08), you can create such as user through Admin > Users > Manage Users.

Setting up Postman

1. Create a new collection
2. Create a new Environment to use with this collection (to hold variables).
   
   • sessionKey (secret) - leave blank
   • hostname (default) - set to your communities hostname (URL without https://)
   • username (default) - set to user created in community admin (or your username if local user)
   • password (secret) - the users community password
   • tapestry (default) - set to t5 (except for some special circumstances)
   • sessionStartTime (default) - leave blank
   • sessionLastUsed (default) - leave blank
   • ht_username (default) - set if you need to login to the community with basic auth credentials (the browser login popup)
   • ht_password (secret) - set if you need to login to the community with basic auth credentials (the browser login popup)
3. In the collection pre-request script, add the pre-request script (included below)
4. Create a new request in your collection
   1. Set the path to be POST https://{{hostname}}/{{tapestry}}/s/api/2.1/graphql
   2. Update headers:
      Key: li-api-session-key
      Value: {{sessionKey}}
5. In the request body, add your GraphQL
6. Execute Query
7. Save your Query (and collection)

 

Collection Pre-Request Script

var sessionKey = pm.environment.get("sessionKey");
var hostname = pm.environment.get("hostname");
var tapesty = pm.environment.get("tapestry");
var ht_username = pm.environment.get("ht_username");
var ht_password = pm.environment.get("ht_password")
var username = pm.environment.get("username");
var password = pm.environment.get("password");
var sessionStartTime = pm.environment.get("sessionStartTime","");
var sessionLastUsed = pm.environment.get("sessionLastUsed","");

const thirtyMinsAgo = Date.now() - (1000 * 60 * 30);
const twoHoursAgo = Date.now() - (1000 * 60 * 60 * 2);

if (sessionLastUsed == "" || sessionStartTime == "" || sessionLastUsed < thirtyMinsAgo || sessionStartTime < twoHoursAgo || sessionKey == "") {
    console.log("authenticating");
    authenticate();
} else {
    pm.environment.set("sessionLastUsed", Date.now());
}

function authenticate(){
    
    const request = {
        url: `https://${hostname}/${tapesty}/s/restapi/vc/authentication/sessions/login?user.login=${username}&user.password=${password}&restapi.response_format=json`,
        method: 'POST',
        header: {
            'Authorization': 'Basic '+btoa(`${ht_username}:${ht_password}`)
        },
    };
    pm.sendRequest(request, function (err, response) {
        if (err) {
            console.error(err);
            pm.execution.skipRequest();
            return;
        }
        const data = response.json();
        if (typeof (data.response.error) !== 'undefined' && typeof (data.response.error.message) !== 'undefined') {
            console.error(data.response.error.message);
            pm.execution.skipRequest();
            throw new Error("Authentication failed (see console)");
        } else {
            console.log("key", data.response.value.$)
            pm.environment.set("sessionKey", data.response.value.$);
            pm.environment.set("sessionStartTime", Date.now());
            pm.environment.set("sessionLastUsed", Date.now());
        }
    });
}

Optional Post-Response script

if (pm.response.code == 401){
    console.warn("Got unauthenticated response. Clearing variables.");
    pm.environment.set("sessionKey","");
    pm.environment.set("sessionLastUsed","");
    pm.environment.set("sessionStartTime","");
}