--- title: Sessions description: "--- ###### Elements utilizes Sessions in order for the client [Application](https://namazustudios.com/glossary/application/) to securely communicate with Elements APIs. All HTTP requests between the client [Application](https://namazustudios.com/glossary/application/) and Elements APIs can have a [Session](https://namazustudios.com/glossary/session/) key. Creating a [Session](https://namazustudios.com/glossary/session/) may be completed through several…" url: "https://namazustudios.com/docs/namazu-elements-core/sessions/" updated: "2026-08-15" category: Namazu Elements Core Features --- # Sessions --- ###### Elements utilizes Sessions in order for the client [Application](https://namazustudios.com/glossary/application/) to securely communicate with Elements APIs. All HTTP requests between the client [Application](https://namazustudios.com/glossary/application/) and Elements APIs can have a [Session](https://namazustudios.com/glossary/session/) key. Creating a [Session](https://namazustudios.com/glossary/session/) may be completed through several API calls. There are multiple ways to create a [Session](https://namazustudios.com/glossary/session/) as detailed in this document. Elements recognizes the following [Session](https://namazustudios.com/glossary/session/) headers: - `Authorization: [bearer] {secret}` - `secret` **(Required):** The [Session](https://namazustudios.com/glossary/session/) secret (See [Creation Methods](#creation-methods) below for more information.) - `Elements-SessionSecret: {secret} [u{UserId}] [p{ProfileId}]` - `secret` **(Required):** The [Session](https://namazustudios.com/glossary/session/) secret (See [Creation Methods](#creation-methods) below for more information.) - `userId` **(Optional):** The [id](https://namazustudios.com/glossary/id/) of a [User](https://namazustudios.com/glossary/user/). If the secret matches a [Super User](../users-and-profiles#user-properties) then this may be any other non Super [User](https://namazustudios.com/glossary/user/) in Elements. This will cause the subsequent request to be executed as the specified [User](https://namazustudios.com/glossary/user/). For all other Users, this must be the identity associated with the [Session](https://namazustudios.com/glossary/session/) making the request. This will override the [User](https://namazustudios.com/glossary/user/) [Scoping Rules](#scoping-rules). - `profileId` **(Optional):** The [id](https://namazustudios.com/glossary/id/) of a [Profile](https://namazustudios.com/glossary/profile/). If the secret matches a [Super User](../users-and-profiles#user-properties) then this may be any [Profile](https://namazustudios.com/glossary/profile/) in Elements. For all other Users, this must be a [Profile](https://namazustudios.com/glossary/profile/) associated with the [User](https://namazustudios.com/glossary/user/) making the request. Ths will override the [Profile Scoping Rules](#profile). ### Creation Methods [#creation-methods](#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 [#username-and-password](#username-and-password) This the most basic method of creating a [Session](https://namazustudios.com/glossary/session/) and requires no third-party integration. When creating a [User](https://namazustudios.com/glossary/user/), the client supplies the desired username and password. Elements securely hashes each [User](https://namazustudios.com/glossary/user/)'s password in the database. To attach a [Profile](https://namazustudios.com/glossary/profile/) to the [Session](https://namazustudios.com/glossary/session/), the request may specify one of `profileId`, `profileSelector`, or (*Elements 3.9+*) `applicationNameOrId` -- the [name](https://namazustudios.com/glossary/name/) or [id](https://namazustudios.com/glossary/id/) of an [Application](applications) whose primary [Profile](https://namazustudios.com/glossary/profile/) should be attached. `applicationNameOrId` is only consulted if neither `profileId` nor `profileSelector` is specified, and if the [Application](https://namazustudios.com/glossary/application/) or the [User](https://namazustudios.com/glossary/user/)'s primary [Profile](https://namazustudios.com/glossary/profile/) for it can't be resolved, the [Session](https://namazustudios.com/glossary/session/) is simply created without a [Profile](https://namazustudios.com/glossary/profile/) rather than failing the request. The same `applicationNameOrId` field is also accepted on [OAuth2](https://namazustudios.com/glossary/oauth2/) [Session](https://namazustudios.com/glossary/session/) creation (see below). #### SSO using [OIDC](https://namazustudios.com/glossary/oidc/) / [OAuth2](https://namazustudios.com/glossary/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](https://namazustudios.com/glossary/user/) to multiple external ids. These services must follow the [OIDC](https://namazustudios.com/glossary/oidc/) or [OAuth2](https://namazustudios.com/glossary/oauth2/) specifications. See [Auth Schemes](auth-schemes) for more details on how this works. Note that logging in through one of these services never merges into a [Session](https://namazustudios.com/glossary/session/) you already hold — to attach an additional identity to an account you're already signed into, see [Account Linking](account-linking) instead. ### Scoping Rules [#scoping-rules](#scoping-rules) Within the Elements [Security Model](../general/security-model), sessions may have two scopes: [User](https://namazustudios.com/glossary/user/) or [Profile](https://namazustudios.com/glossary/profile/). Some APIs require a [Session](https://namazustudios.com/glossary/session/) with a current [Profile](https://namazustudios.com/glossary/profile/) and not just a [User](https://namazustudios.com/glossary/user/). Generally these APIs are for [Application](https://namazustudios.com/glossary/application/) specific operations, such as Matchmaking. #### [User](https://namazustudios.com/glossary/user/) [#user](#user) All sessions will have a [User](https://namazustudios.com/glossary/user/) associated with them. Once created, they will always be valid for that [User](https://namazustudios.com/glossary/user/) until it expires or the [User](https://namazustudios.com/glossary/user/) changes their password. #### [Profile](https://namazustudios.com/glossary/profile/) [#profile](#profile) A [Session](https://namazustudios.com/glossary/session/) may, optionally, be scoped by a [User](https://namazustudios.com/glossary/user/) and a [Profile](https://namazustudios.com/glossary/profile/). The [Profile](https://namazustudios.com/glossary/profile/)'s owner must match the [User](https://namazustudios.com/glossary/user/) who created the [Session](https://namazustudios.com/glossary/session/). APIs that require [Profile](https://namazustudios.com/glossary/profile/) scoping rules are as follows: - Fetching current [Profile](https://namazustudios.com/glossary/profile/) (eg GET /[Profile](https://namazustudios.com/glossary/profile/)/current) - Processing IAPs - Leaderboards and Rankings - Push Notifications - Progress and Missions