Change the security principal and credentials associated with your client session

A client session can change the credentials it uses to authenticate with the Diffusion™ server at any time.

JavaScript

session.security.changePrincipal('principal', 'password').then(function() {
        console.log('Authenticated as admin');
    });

.NET


security = session.Security;
security.ChangePrincipal( principal, Diffusion.Credentials.Password( password ), callback );

Java and Android

security = session.feature(Security.class);
security.changePrincipal(
    principal,
    Diffusion.credentials().password(password),
    callback);

// Specify callbacks for the change_principal request.
CHANGE_PRINCIPAL_PARAMS_T params = {
        .principal = hash_get(options, "principal"),
        .credentials = credentials,
        .on_change_principal = on_change_principal,
        .on_change_principal_failure = on_change_principal_failure
};

// Do the change.
change_principal(session, params);

Apple

// Create a credentials object encapsulating a string password.
PTDiffusionCredentials *const credentials =
    [[PTDiffusionCredentials alloc] initWithPassword:@"password"];

// Use the Security feature from your session...
[session.security changePrincipal:@"principal"
                      credentials:credentials
                completionHandler:^(NSError *error)
{
    // Check error is `nil`, indicating success.
}];

When the principal associated with a session changes, the following happens:

The $Principal session property is updated to contain the new principal.
The roles associated with the old principal are removed from the session and those roles associated with the new principal are assigned to the session.
Topic subscriptions made with the old principal are not re-evaluated. The session remains subscribed to any topics the new principal does not have permissions for.