PUT /authenticate

How did we do?

Authenticates a user into your game or project, using the credentials provided.

Outline

This endpoint allows you to authenticate a user in your game, using token-based authentication (such as Steam), password-based authentication, or a combination of both. It fully supports two-factor authentication and account linking.

When your game first starts up, it should send a request to this endpoint with all of the tokens it currently has access to (such as Steam authentication tickets). If this is enough to authenticate a user, HiveMP will return the newly created user session as part of the response.

If additional information is required from the user, the response will set boolean flags indicating what information your game should request from them. Once you've obtained that information, attach it to your authentication request and send the request again. This process repeats until HiveMP has enough information to authenticate the user.

For error scenarios, such as invalid password, HiveMP will instead return an error the same way other API endpoints return errors. However, you shouldn't discard the current state of prompting the user when this occurs; if HiveMP is currently requesting that your game prompt the user for their password, your game should continue to prompt for the password even when receiving an error from this endpoint (but include the error message somewhere suitable in the UI).

This endpoint is also used for administrative-based logins to your project. If the client app that is logging in with administrative access does not know the project the user wants to administer, the authentication request should have promptForProject set to true. If the user does not have administrative access to any projects in this case, the system will create a new default project for the user and automatically select it.

Request

HTTP request

PUT https://sessions-api.hivemp.com/v1/authenticate

You must replace the emphasized parameter values when making the request. Refer to the parameters section below.

Access policies

This method can only be called with certain kinds of API keys. The API key types that are permitted to call this API are:

Additional restrictions may apply to some of the API key types listed above; refer to the method description for any additional restrictions.

Authorization

All HiveMP REST APIs require the presence of an X-API-Key header with an appropriate value, depending on the access policies outlined above.

This method requires a valid API key to be passed on request, as demonstrated in the following example:

X-API-Key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Parameters

authentication Description The authentication request with all the information your app currently has to perform authentication.
Type AuthenticationRequest
Specified In body

Required? No

Request body

You must pass the value of authentication as the request body.

Response

This method will return one of the following responses:

200 Description Success
Type AuthenticationResponse
... Description An error occurred; check the value error code and message of the response
Type HiveMPSystemError

Code Snippets

read -r -d '' _request_body << EOM
null
EOM
curl -s \
  -H "X-API-Key: $apiKey" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data "..." \
  -X PUT \
  "https://user-session-api.hivemp.com/v1/authenticate"
// At the top of your script.
using HiveMP.Api;
using HiveMP.UserSession.Api;

// Inside your MonoBehaviour. Callbacks automatically happen on the main thread
// via Unity's coroutine infrastructure.
var client = new UserSessionClient("<YOUR API KEY HERE>");
client.AuthenticatePUTPromise(new AuthenticatePUTRequest
    {
        Authentication = null,
    },
    result =>
    {
        // result is an AuthenticationResponse
    },
    ex =>
    {
        // HiveMP exception properties:
        // - ex.HttpStatusCode: The HTTP status code of the response
        // - ex.HiveErrorCode: The HiveMP error code
        // - ex.HiveErrorMessage: The HiveMP error message
        // - ex.HiveErrorFields: Arbitrary extra data associated with the error
    });
// Add to your namespaces.
using HiveMP.Api;
using HiveMP.UserSession.Api;

// Call this inside an async method.
var client = new UserSessionClient("<YOUR API KEY HERE>");
try
{
    var result = await client.AuthenticatePUTAsync(new AuthenticatePUTRequest
        {
            Authentication = null,
        });
    
// result is an AuthenticationResponse } catch (HiveMPException ex) { // HiveMP exception properties: // - ex.HttpStatusCode: The HTTP status code of the response // - ex.HiveErrorCode: The HiveMP error code // - ex.HiveErrorMessage: The HiveMP error message // - ex.HiveErrorFields: Arbitrary extra data associated with the error }
# Copy the text below into a Blueprints window
# inside the UE4 editor anywhere to create the node for
# this API call.
Begin Object Class=/Script/OnlineBlueprintSupport.K2Node_LatentOnlineCall Name="K2Node_LatentOnlineCall_0"
   ProxyFactoryFunctionName="PerformHiveCall"
   ProxyFactoryClass=Class'/Script/HiveMPSDK.sessions_UserSession_'
   ProxyClass=Class'/Script/HiveMPSDK.sessions_UserSession_'
End Object

Try this API

The API key to use for the request.

The authentication request with all the information your app currently has to perform authentication.