Authenticate User
{ authenticateUser }
Generates an access authentication token for the given user to use the API functions or login to the application.
Method
- Enterprise Admin
- Domain Admin
- Pro
- Analyst
- Viewer
- Basic
Input Parameters
Name
userCredentials
Object Type
Description
The user credential object used to set a user's login settings.
Output Response
Successful Result Code
200
Response Type
string
Description of Response Type
The response is the security token as a base64 string. It is usually stored in a cookie.
Notes
The security token is a string that needs to be embedded in every API call to ensure the API calls are authorized. If saved as a cookie in a web browser, it can be used (for the authenticated user) to auto-login into the application.
Examples
This example demonstrates how to authenticate users for the main application.
using System;
using System.Linq;
using System.Web;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
namespace CsWebSite
{
public partial class Default : System.Web.UI.Page
{
public const String API_PATH = "http://mySite.com/API3/";
protected void Page_Load(object sender, EventArgs e)
{
//logging the user
String adminToken = getToken("authenticateUser", new
{
userName = "adminUser1",
password = "abc123!"
});
String userToken = getToken("authenticateUserByToken", new
{
userIdentity = "userName",
token = adminToken
});
//this cookie should be placed on the domain pyramid is installed on - mySite.com in this example
Response.Cookies.Add(new HttpCookie("PyramidAuth", userToken));
}
//generic method for getting the token via REST
private String getToken(String service, Object data)
{
HttpClient client = new HttpClient();
StringContent content = null;
content = new StringContent(JsonConvert.SerializeObject(data), Encoding.UTF8, "application/json");
Task<HttpResponseMessage> response = client.PostAsync(API_PATH + "authentication/" + service, content);
return response.Result.Content.ReadAsStringAsync().Result;
}
}
}
This example demonstrates how to authenticate users for the main application.
import com.sun.net.httpserver.HttpExchange;
import com.sun.net.httpserver.HttpHandler;
import com.sun.net.httpserver.HttpServer;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.BasicResponseHandler;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClientBuilder;
import org.json.simple.JSONObject;
import java.io.IOException;
import java.net.InetSocketAddress;
public class Main {
private static final String pyramidPath = "http://mySite.com/API3/";
public static void main(String[] args) throws IOException {
HttpServer server = HttpServer.create(new InetSocketAddress(8000), 0);
server.createContext("/login", new LoginHandler());
server.setExecutor(null); // creates a default executor
server.start();
}
private static class LoginHandler implements HttpHandler {
@Override
public void handle(HttpExchange httpExchange) throws IOException {
//logging the user
JSONObject adminCredentials = new JSONObject();
adminCredentials.put("userName", "testUser1");
adminCredentials.put("password", "abc456!");
String adminToken = getToken("authenticateUser", adminCredentials);
//logging the user in using the admin's token
JSONObject userCredentials = new JSONObject();
userCredentials.put("userIdentity", "test.user1@mySite.com");
userCredentials.put("token", adminToken);
String userToken = getToken("authenticateUserByToken", userCredentials);
//searching the user by name
JSONObject results = callApi("access/getUsersByName", "testUser1", adminToken);
String userId = ((JSONObject) ((JSONArray) results.get("data")).get(0)).get("id").toString();
//reading the user's private folder
JSONObject privateFolder = callApi("content/getFolderItems",
userId,//the user private folder id is the same as the user id
adminToken
);
String messageStr = "private folder id is " + userId + " and it contains ";
JSONArray folderContent = ((JSONArray) privateFolder.get("data"));
for (int i = 0; i < folderContent.size(); ++i) {
messageStr += ((JSONObject) folderContent.get(i)).get("caption") + ",";
}
byte[] message = messageStr.getBytes(StandardCharsets.UTF_8);
httpExchange.getResponseHeaders().add("Set-Cookie", "PyramidAuth=" + userToken);
httpExchange.sendResponseHeaders(200, message.length);
httpExchange.getResponseBody().write(message);
}
}
protected static String getToken(String service, JSONObject data) throws IOException {
return sendPost("authentication/" + service, data.toJSONString(),null);
}
protected static String sendPost(String path, String data, String token) throws IOException {
try (CloseableHttpClient httpClient = HttpClientBuilder.create().build()) {
String address = pyramidPath + path;
HttpPost request = new HttpPost(address);
StringEntity params = new StringEntity(data);
request.addHeader("content-type", "application/x-www-form-urlencoded");
if (token !=null) {
request.addHeader("paToken", token);
}
request.setEntity(params);
CloseableHttpResponse response = httpClient.execute(request);
return new BasicResponseHandler().handleResponse(response);
}
}
}
This example demonstrates how to authenticate a user from JavaScript.
// URL of the Pyramid installation and the path to the API 3.0 REST methods
var pyramidURL = "http://mysite.com/api3/";
// step 1: authenticate user account and get token
// NOTE: callApi method is a generic REST method shown below.
let token = callApi("authentication/authenticateUser",{
"userName":"aUser",
"password":"abc123!"
},"",false);
log("got token "+token);
// step 2: get the current user's ID
let currentUser= callApi("access/getMe",
{},token
);
// step3: get the user's ID from the response
let userId = currentUser[0];
// ##### optional generic login method for debugging ##############
function log(msg){
document.write(msg);
console.log(msg);
}
// ##### generic REST API calling method ##############
function callApi(path,data,token="",parseResult=true){
var xhttp = new XMLHttpRequest();
xhttp.open("POST", pyramidURL+path, false);
xhttp.setRequestHeader("paToken",token)
xhttp.send(JSON.stringify(data));
if(parseResult){
return JSON.parse(xhttp.responseText);
}else{
return xhttp.responseText;
}
}
Code Snippets
curl -X POST \
-H "Accept: text/plain,text/plain;charset=utf-8" \
-H "Content-Type: application/json" \
"http://Your.Server.URL/API3/authentication/authenticateUser" \
-d '{
"password" : "password",
"domain" : "domain",
"customData" : "customData",
"username" : "username"
}'
import com.pyramidanalytics.*;
import com.pyramidanalytics.auth.*;
import com.pyramidanalytics.model.*;
import com.pyramidanalytics.api.AuthenticationServiceApi;
import java.util.*;
import java.time.*;
public class AuthenticationServiceApiExample {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
defaultClient.setBasePath("http://Your.Server.URL/");
// Create an instance of the API class
AuthenticationServiceApi apiInstance = new AuthenticationServiceApi();
// Initialize the userCredentials parameter object for the call
UserCredentials userCredentials = ; // Create the input object for the operation, type: UserCredentials
try {
String result = apiInstance.authenticateUser(userCredentials);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling AuthenticationServiceApi#authenticateUser");
e.printStackTrace();
}
}
}
import * as PyramidAnalyticsWebApi from "com.pyramidanalytics";
// Create an instance of the API class
const api = new PyramidAnalyticsWebApi.AuthenticationServiceApi("http://Your.Server.URL")
const userCredentials = ; // {UserCredentials}
api.authenticateUser(userCredentials).then(function(data) {
console.log('API called successfully. Returned data: ' + data);
}, function(error) {
console.error(error);
});
using System;
using System.Diagnostics;
using PyramidAnalytics.Sdk.Api;
using PyramidAnalytics.Sdk.Client;
using PyramidAnalytics.Sdk.Model;
public class authenticateUserExample
{
public static void Main()
{
Configuration conf = new Configuration();
conf.BasePath = "http://Your.Server.URL/";
GlobalConfiguration.Instance = conf;
// Create an instance of the API class
var apiInstance = new AuthenticationServiceApi();
// Initialize the userCredentials parameter object for the call
var userCredentials = new UserCredentials(); // UserCredentials |
try {
// Generates an access authentication token for the given user to use the API functions or login to the application.
string result = apiInstance.authenticateUser(userCredentials);
Debug.WriteLine(result);
} catch (Exception e) {
Debug.Print("Exception when calling AuthenticationServiceApi.authenticateUser: " + e.Message );
}
}
}
import com.pyramidanalytics
from com.pyramidanalytics import ApiException
from com.pyramidanalytics import AuthenticationServiceApi
from pprint import pprint
api_config = com.pyramidanalytics.Configuration(host = 'http://Your.Server.URL')
with com.pyramidanalytics.ApiClient(api_config) as api_client:
# Create an instance of the API class
api_instance = AuthenticationServiceApi(api_client)
# Initialize the userCredentials parameter object for the call
userCredentials = # UserCredentials |
try:
# Generates an access authentication token for the given user to use the API functions or login to the application.
api_response = api_instance.authenticate_user(userCredentials)
pprint(api_response)
except ApiException as e:
print("Exception when calling AuthenticationServiceApi->authenticateUser: %s\n" % e)
<?php
require_once(__DIR__ . '/vendor/autoload.php');
OpenAPITools\Client\Configuration::getDefaultConfiguration()->setHost('http://Your.Server.URL');
// Create an instance of the API class
$api_instance = new OpenAPITools\Client\Api\AuthenticationServiceApi();
$userCredentials = ; // UserCredentials |
try {
$result = $api_instance->authenticateUser($userCredentials);
print_r($result);
} catch (Exception $e) {
echo 'Exception when calling AuthenticationServiceApi->authenticateUser: ', $e->getMessage(), PHP_EOL;
}
?>