Elements utilizes Sessions in order for the client application to securely communicate with Elements APIs. #
All HTTP requests between the client application and Elements APIs can have a session key. Creating a Session may be completed through several API calls. There are multiple ways to create a session as detailed in this document.
Elements recognizes the following session headers:
Authorization: [bearer] {secret}secret(Required): The Session secret (See Creation Methods below for more information.)Elements-SessionSecret: {secret} [u{UserId}] [p{ProfileId}]secret(Required): The Session secret (See Creation Methods below for more information.)userId(Optional): The id of a User. If the secret matches a Super User then this may be any other non Super User in Elements. This will cause the subsequent request to be executed as the specified User. For all other Users, this must be the identity associated with the session making the request. This will override the User Scoping Rules.profileId(Optional): The id of a Profile. If the secret matches a Super User then this may be any Profile in Elements. For all other Users, this must be a Profile associated with the User making the request. Ths will override the Profile Scoping Rules.
Creation Methods #
There are several ways to create sessions within Elements. Each section here describes the supported creation methods and how to implement each one of them. In all cases, Elements performs the account verification authoritatively, ensuring that the server has verified the credentials supplied to it.
Username and Password #
This the most basic method of creating a session and requires no third-party integration. When creating a User, the client supplies the desired username and password. Elements securely hashes each User’s password in the database.
SSO using OIDC / OAuth2 #
Elements provides the ability to create and customize Single Sign On (SSO) options for a variety of services, and even connect a single User to multiple external ids. These services must follow the OIDC or OAuth2 specifications. See Auth Schemes for more details on how this works.
Scoping Rules #
Within the Elements Security Model, sessions may have two scopes: User or Profile. Some APIs require a session with a current Profile and not just a User. Generally these APIs are for application specific operations, such as Matchmaking.
User #
All sessions will have a User associated with them. Once created, they will always be valid for that User until it expires or the user changes their password.
Profile #
A Session may, optionally, be scoped by a User and a Profile. The Profile’s owner must match the User who created the session. APIs that require Profile scoping rules are as follows:
- Fetching current Profile (eg GET /profile/current)
- Processing IAPs
- Leaderboards and Rankings
- Push Notifications
- Progress and Missions