Authenticate User for Embedding

{ authenticateUserEmbed }

Generates an access authentication token for the given user to use the embedded content functionality.



  • API Section: /API2/auth
  • API Version: 2.0
  • From Release: 2018.5
  • Can be used by Non-admin accounts
  • Method operates via POST actions only.
  • Input Parameters



    Object Type


    The user credential object used to set a user's login settings.

    Output Response

    Successful Result Code


    Description of Response Type

    The response is the security token as base64 string. It is usually stored in a cookie.


    The security token is a string that needs to be added to a cookie on the third party host page for any embedded content to ensure the access is authorized.

    User Embed Authentication (C#):

    This example demonstrates how to authenticate users for embedding.

    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 = "";
    		protected void Page_Load(object sender, EventArgs e)
    			//logging the user for embed
    			String adminTokenEmbed = getToken("authenticateUserEmbed", new
    			{ 	data = new {
    					userName = "adminUser1",
    					password = "abc123!",
    					domain = ""
    			//alternative embed using the admim user token (so not requiring the user's password)
    			String userTokenEmbed = getToken("authenticateUserEmbedByToken", new
    				userIdentity = "userName",
    				token = adminTokenEmbed
    			//this cookie should be applied at, assuming is installed on a diffrent domain
    			Response.Cookies.Add(new HttpCookie("PyramidEmbeddedAuth", 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 + "auth/" + service, content);
    			return response.Result.Content.ReadAsStringAsync().Result;
    		//generic method for running REST methods
    		private JToken callApi(String service, Object data, String token)
    			HttpClient client = new HttpClient();
    			StringContent content = null;
    			data = new { auth = token, data = data };
    			content = new StringContent(JsonConvert.SerializeObject(data), Encoding.UTF8, "application/json");
    			Task>HttpResponseMessage< response = client.PostAsync(API_PATH + service, content);
    			String resultStr = response.Result.Content.ReadAsStringAsync().Result;
    			if (resultStr.Count() == 0)
    				return null;
    			return JsonConvert.DeserializeObject>JObject<(resultStr)["data"];
    User Embed Authentication (Java):

    This example demonstrates how to authenticate users for embedding.

    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;
    public class Main {
    	private static final String pyramidPath = "";
    	public static void main(String[] args) throws IOException {
    		HttpServer server = HttpServer.create(new InetSocketAddress(8000), 0);
    		server.createContext("/embed", new EmbedHandler());
    		server.setExecutor(null); // creates a default executor
    	private static class EmbedHandler implements HttpHandler {
    		public void handle(HttpExchange httpExchange) throws IOException {
    			//logging the user
    			JSONObject adminCredentials = new JSONObject();
    			adminCredentials.put("userName", "adminUser1");
    			adminCredentials.put("password", "abc123!");
    			adminCredentials.put("domain", "");
    			String adminToken = getToken("authenticateUserEmbed", adminCredentials);
    			//getting user's embed token using the admin's authenctication token
    			JSONObject userCredentials = new JSONObject();
    			adminCredentials.put("userIdentity", "JohnSmith");
    			adminCredentials.put("token", adminToken);
    			String userToken = getToken("authenticateUserEmbedByToken", userCredentials);
    			//setting the cookie PyramidEmbeddedAuth to userToken
    			byte[] message = "you logged in".getBytes();
    			httpExchange.getResponseHeaders().add("Set-Cookie", "PyramidEmbeddedAuth=" + userToken);
    			httpExchange.sendResponseHeaders(200, -1);
    	protected static String getToken(String service, JSONObject data) throws IOException {
    		JSONObject dataHolder = new JSONObject();
    		dataHolder.put("data", data);
    		return sendPost("auth/" + service, dataHolder.toJSONString());
    	protected static String sendPost(String path, String data) 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");
    			CloseableHttpResponse response = httpClient.execute(request);
    			return new BasicResponseHandler().handleResponse(response);