Security Model

Levels of Access for Users

Each API provides three basic level of access:

  1. Anonymous (or Unprivileged) provides access to information that is considered public. Few APIs will supply information when used without any kind of credentials. Some APIs may only return limited sets of data at this level.
  2. User is the level of access for all authenticated users. This is what the average user will use when accessing your applications. When creating new accounts, the system will automatically assign users to this level of access.
  3. Administrator (or Superuser) allows for complete control over the system. APIs may return all information requested. Admins may perform operations such editing user accounts, resetting passwords for other users in the system, or adjust the application parameters. Using the admin console requires superuser access.

Elements provides a Swagger definition for its APIs with every release. When running the local instance, you may always access the latest documentation at http://localhost:8080/api to see the current documentation for the deployed build.

Additionally, when troubleshooting, it is often times useful to fetch the version endpoint which prints out the revision, build time, and version number by visiting this link in your local browser http://localhost:8080/api/localhost/version. This information should also be visible upon logging in to the admin console.

At the time of this writing, user segmentation is not fully supported. (TODO: Describe in more detail)

Single Sign-On

Facebook Single Sign-On

Elements supports SSO through Facebook OAuth Tokens. This enables your app to support Facbook integration out of the box without having to touch a single line of server code. When creating users via Facebook.

To support Facebook authentication in your app, perform the following steps:

  1. If you have not done so, create an Application in the Elements Admin Console
  2. Create an app in Facebook Developer Portal
  3. Create a Facebook Application Configuration within the Application
  4. Copy and Paste in the App ID and Application Secret
  5. Save the Application Configuration

TODO: Add detail on lua code samples to get this running

Apple Sign-In

Elements supports SSO through Apple Sign-In, to help you meet Apple's iOS app requirements.

For details on setting up Apple Sign-In in the console, see Application Configurations.

TODO: Add detail on lua code samples to get this running

Username/Password Sign-In

Username/password sign in is the default method of authentication within Elements.

Create new User

When someone signs up for Elements (via the UserSignupApi), they must provide a user name, a password, and an email address. This will provide you with the new User object in the response, which will be needed for the next step.

Sign in with existing User

After creating the new User, or if someone has already created a User in Elements, they can retrieve a session key with just the Username and Password via the UsernamePasswordSessionApi. This will return a SessionCreation object that contains the SessionSecret property, which is your session key.

Once the session key has been retrieved, you can then authenticate User related requests by adding the session key to the singleton client configuration in your generated code. For example:

Server.Elements.Client.Configuration.ApiKey["Elements-SessionSecret"] = <SessionSecret>;


There will likely be two configurations, one for Elements and one for your application. It will be necessary to add the same session secret to both of these.

Adding this will automatically add the session key to any requests that require auth.


Most requests are profile related, so we are not quite done with the login process yet.

Now that the session secret for the User has been acquired, we can either retrieve all of the Profiles for that User, or create a new Profile.

Create New Profile

Creating a new Profile will require a reference to the Application that it's being created for. See Users and Profiles for more information on the relationship structure. The CreateProfileRequest object used to create a new Profile contains the following properties:

  • UserId (Required)
  • ApplicationId (Required)
  • DisplayName (Required, can be changed later)
  • ImageUrl (Optional, can be changed later)

The CreateProfile request will give you the created Profile object if the request was successful.

Fetch Existing Profiles

If someone has already created a Profile and simply wishes to log back in to that Profile, then you can retrieve all profiles for a User and Application using the GetProfiles via the ProfilesApi. At this point it's up to you to decide whether to let someone choose their Profile (for example, if you have a game that allows for multiple characters) or to choose for them.

Add Profile Id to Session Key

Once the Profile has been acquired, to authenticate any Profile specific requests (e.g. Progress), the Profile Id must be appended to the session key using the following format:

//Session key string, then <space>, then 'p', then the profile id
<session key> p<profile id>

once this is created, overwrite the previous session key stored in the API configurations, for example:

Server.Elements.Client.Configuration.ApiKey["Elements-SessionSecret"] = <New Session Secret>;

and with this, the login process is complete!