Skip to content

Custom sign-in

An https endpoint of your own, on port 443, that answers who the client is. The platform calls it with the payload the game sent, signed with a secret, and reads the identity from the answer.

Choose an environment in the header, open Project settings → Authentication and add a Custom sign-in connection.

FieldMeaning
UrlAn https address on port 443 without user info, such as https://auth.example.com/rudder.
SecretEnter your secret, or leave it empty for Rudder to generate one. It is shown once after saving.

The game sends the object you and your server agreed on.

import { Session } from '@rudder/sdk';
const session = await Session.signIn(key, {
provider: 'web-login',
payload: { token },
});
using RudderSdk;
var session = await Session.SignInAsync(key, new ProviderSignIn
{
Provider = "web-login",
Payload = new Dictionary<string, object?> { ["token"] = token },
});

web-login here is the name you gave the connection, not a provider kind.

The platform posts the payload to your URL:

POST https://auth.example.com/rudder
Content-Type: application/json
X-Rudder-Timestamp: 1761744000
X-Signature: 2196d2aa9a9a873ce1fa833820701ba041c08780a2e4af11b03cd6e224c91e08
{"customData":{"token":"abc"}}
  • customData is exactly the payload of the client: a JSON object of at most 16 KB and at most 32 keys. The platform does not look inside it.
  • X-Rudder-Timestamp is the Unix time in seconds.
  • X-Signature is the hex HMAC-SHA256 of <timestamp>.<body> with the provider secret, where <body> is the exact bytes of the request body.

The call waits three seconds and is not retried. At most 32 are in flight at once.

  1. Read the raw body bytes — before any JSON parser touches them.
  2. Take X-Rudder-Timestamp and the provider secret.
  3. Compute HMAC-SHA256(secret, timestamp + "." + body) and compare it with X-Signature in constant time.
  4. Reject the request when the signature does not match, or the timestamp is more than 5 minutes away from your clock.

Only then trust customData.

{"subject": "account-42", "nickname": "Ada", "avatarUrl": "https://cdn.example.com/ada.png"}

subject is required, 1–256 bytes, and unique among the accounts of this provider: a changed subject signs the player in as a new one. nickname (at most 32 characters) and avatarUrl (an http or https address) fill what the player does not have yet.

  • 200 with the JSON above signs the player in.
  • Any other 4xx answers the client 401 unauthorized.
  • Anything else — another status, a timeout, a body that is not JSON, a missing subject or a bad avatar — answers 503 try_again.

The rest are in Errors.