--- title: OAuth2 description: "--- ###### When creating a new [Session](https://namazustudios.com/glossary/session/), you have the option to authenticate using a predefined [OAuth2](https://namazustudios.com/glossary/oauth2/) Auth Scheme. ## [OAuth2](https://namazustudios.com/glossary/oauth2/) Auth Scheme Anatomy [OAuth2](https://namazustudios.com/glossary/oauth2/) Auth Schemes are comprised of: - the Scheme [name](https://namazustudios.com/glossary/name/) - a Validation URL, which Elements…" url: "https://namazustudios.com/docs/namazu-elements-core/user-authentication-sign-in/auth-schemes/oauth2/" updated: "2026-08-13" category: Namazu Elements Core Features / User Authentication / Sign In / Auth Schemes --- # OAuth2 --- ###### When creating a new [Session](https://namazustudios.com/glossary/session/), you have the option to authenticate using a predefined [OAuth2](https://namazustudios.com/glossary/oauth2/) Auth Scheme. ## [OAuth2](https://namazustudios.com/glossary/oauth2/) Auth Scheme Anatomy [OAuth2](https://namazustudios.com/glossary/oauth2/) Auth Schemes are comprised of: - the Scheme [name](https://namazustudios.com/glossary/name/) - a Validation URL, which Elements will use to validate the token it receives - the Response [id](https://namazustudios.com/glossary/id/) Mapping, which Elements will use to get the [User](https://namazustudios.com/glossary/user/) [id](https://namazustudios.com/glossary/id/) from the validation request (see below for example) - a list of Headers and a list of Parameters for the validation request, which can be predefined, or sent from the client and filled in by Elements before making the validation request ![](https://namazustudios.com/wp-content/uploads/2025/08/Screenshot-2026-01-23-at-3.49.36-PM-1024x270.png) ![](https://namazustudios.com/wp-content/uploads/2025/08/Screenshot-2026-01-23-at-3.48.07-PM-1024x889.png) Since the requirements for [OAuth2](https://namazustudios.com/glossary/oauth2/) vary by provider, we've created a system that is flexible enough for any spec. For instance, some systems, such as Oculus, require that you send the [User](https://namazustudios.com/glossary/user/) [id](https://namazustudios.com/glossary/id/) from the client alongside the validation token. We've added a [User](https://namazustudios.com/glossary/user/) [id](https://namazustudios.com/glossary/id/) flag that allows you to flag either a header, parameter, or body property as the [User](https://namazustudios.com/glossary/user/) [id](https://namazustudios.com/glossary/id/) (only one is allowed) in these instances. In other cases, the [User](https://namazustudios.com/glossary/user/) [id](https://namazustudios.com/glossary/id/) comes back in the response when validating the token. In these cases, we've provided an [id](https://namazustudios.com/glossary/id/) mapper. In any case, it's very important to look at the docs for the oauth provider and understand exactly what they're expecting. Once the validation request comes back successfully, Elements will link the provided/returned [User](https://namazustudios.com/glossary/user/) [id](https://namazustudios.com/glossary/id/) to the internal Elements [User](https://namazustudios.com/glossary/user/) [id](https://namazustudios.com/glossary/id/). ## Auth Scheme Properties Here's a breakdown of the auth scheme properties and what they represent: | **[id](https://namazustudios.com/glossary/id/)** | The Elements database [id](https://namazustudios.com/glossary/id/). | | --- | --- | | **[name](https://namazustudios.com/glossary/name/)** | The unique [name](https://namazustudios.com/glossary/name/) of this scheme in the Elements system. | | **Validation Url** | The URL that the server to server validation request will be sent to. | | **Headers** | Any headers that the validation request might be expecting. Can mark as fromClient, indicating that this will be sent from the client. Otherwise, it assumes that this was predefined in the auth scheme. | | **Params** | Any query parameters that the validation request might be expecting. Can mark as fromClient, indicating that this will be sent from the client. Otherwise, it assumes that this was predefined in the auth scheme. | | **Body** | (POST requests only) Any body parameters that the validation request might be expecting. Can mark as fromClient, indicating that this will be sent from the client. Otherwise, it assumes that this was predefined in the auth scheme. | | **Response [id](https://namazustudios.com/glossary/id/) Mapping** | Determines how to map the [User](https://namazustudios.com/glossary/user/) [id](https://namazustudios.com/glossary/id/) in the response. Will search the response for the corresponding key. For example, if the response is structured like: {"response": { "params" : { "steamid" : <[id](https://namazustudios.com/glossary/id/)> } } } then you only need to input "steamid". Ignored if one of the parameters is marked as [User](https://namazustudios.com/glossary/user/) [id](https://namazustudios.com/glossary/id/). | | **Response Valid Mapping** | Optional key in the response whose value indicates whether the token/[User](https://namazustudios.com/glossary/user/) is valid. For example: "is_valid", "active", or "success". If not set, only the HTTP status code is used. | | **Response Valid Expected Value** | Optional expected value for the validation field. If null: - boolean true is treated as success - non-empty/non-null for non-boolean values is treated as success. If set, the field's string value must equal this. | | **Valid Status Codes** | HTTP status codes that are considered "processable" for validation. Any other status is treated as failure before inspecting the body. Defaults to [200]. | | **Method** | HTTP method for the validation request (GET or POST). | | **Body Type** | How to encode the request body when using POST. FORM_URL_ENCODED corresponds to [Application](https://namazustudios.com/glossary/application/)/x-www-form-urlencoded. | ## Steam Example One of the default [OAuth2](https://namazustudios.com/glossary/oauth2/) Auth Schemes is for authenticating via Steam. We'll use this as an example as to how these can be used. Note It will be necessary to have a registered [Application](https://namazustudios.com/glossary/application/) on Steam, as this process will require an [Application](https://namazustudios.com/glossary/application/) [id](https://namazustudios.com/glossary/id/). The goal here is to have our client [Application](https://namazustudios.com/glossary/application/) retrieve an auth ticket from Steam, then to send that to Elements, which in turn will use the ticket to verify the corresponding [User](https://namazustudios.com/glossary/user/) [id](https://namazustudios.com/glossary/id/). Note This assumes that you already have a process set up to retrieve the auth ticket, either manually as depicted in the [Steam documentation](https://partner.steamgames.com/doc/features/auth#client_to_backend_webapi), or through a client library, such as [Steamworks.net](https://steamworks.github.io/). First let's look at the auth scheme to determine what Elements is expecting: ``` { "id": "683a2311bc53452f7ea04b33", "name": "Steam", "validationUrl": "https://api.steampowered.com/ISteamUserAuth/AuthenticateUserTicket/v1/", "headers": [ { "key": "x-webapi-key", "value": "169AA59968B1FDBA0E303C311C525B8F", "fromClient": false, "userId": false }, { "key": "Content-Type", "value": "application/x-www-form-urlencoded", "fromClient": false, "userId": false } ], "params": [ { "key": "appid", "value": "370140", "fromClient": false, "userId": false }, { "key": "ticket", "value": "Ticket from GetAuthSessionTicket (Sent from frontend)", "fromClient": true, "userId": false }, { "key": "identity", "value": "nebtest", "fromClient": false, "userId": false } ], "responseIdMapping": "steamid", "validStatusCodes": [ 200 ] } ``` We're basically telling it how to format the request that Elements will send to the authenticating server. In this case, we're telling Elements to expect the ticket to be sent from the client (the only header or parameter with `fromClient` as true), and that all other values will be preset in the scheme and stored within Elements. Note When you make the call to GetAuthTicketForWebApi to retrieve the auth ticket, you pass in an identity value. This can be anything (or nothing), but must match on the client and server side. When we make a request against the [/auth/oauth2](../../restful-apis/api-specification/auth_scheme/oauth2) endpoint, Elements will format a new request using the `headers` and `params` information in the scheme, and will send the request to the `validationUrl` defined in the scheme. In this case, we only told the scheme to expect one parameter, `"ticket"`, and no headers from the client, so our request would look like this: ``` Example: POST http://localhost:8080/api/rest/auth/oauth2 Body: { "schemeId":"Steam", "requestParameters" : { "ticket":""" } } ``` When Elements receives the response, it will use the `responseIdMapping` to look for a corresponding key, and will assume the value of this key is the [User](https://namazustudios.com/glossary/user/)'s [id](https://namazustudios.com/glossary/id/). ``` Example response from Steam (handled internally in Elements): { "response": { "params": { "result": "OK", "steamid": "", "ownersteamid": "", "vacbanned": false, "publisherbanned": false } } } ``` If Elements retrieves the [User](https://namazustudios.com/glossary/user/) [id](https://namazustudios.com/glossary/id/) successfully, it will automatically associate this Steam [User](https://namazustudios.com/glossary/user/) [id](https://namazustudios.com/glossary/id/) with an Elements [User](https://namazustudios.com/glossary/user/), and return the [Elements Session](../sessions) object back to you. Once you have the [Session](https://namazustudios.com/glossary/session/) object, just add the `sessionSecret` to the `Elements-SessionSecret` header for subsequent requests, and you're all set!