User

View as Markdown

User

User sends the password reset requests of a Contentstack account, in the Contentstack.Management.Core.Models namespace.

When to Use This Class: Use this class when a user has forgotten the password of a Contentstack account and your tool runs the reset for them.

Conceptual Role: Acts as the Content Management API (CMA) client for the /user/forgot_password and /user/reset_password requests. Call client.User() to get an instance.

Returns: User. A handle for password reset requests.

Instance State

Every User method needs a client without an authtoken, because a password reset is for a user who cannot sign in. Create the client with new ContentstackClient() and no authtoken.

A method called on a client that has an authtoken throws InvalidOperationException before any request. Call Logout first, or use a second client.

Class-Level Notes

The reset takes two steps.

  1. ForgotPassword asks the API to email a reset token to the account.
  2. ResetPassword sends that token with the new password.

Errors.

  • A method that returns without throwing returns a ContentstackResponse with a success status. The SDK throws ContentstackErrorException when the API rejects the request.

Reading the signed-in user.

  • To read the details of the signed-in account, call the GetUser method of ContentstackClient. User has no fetch method.

Method Index

Reset a forgotten password. Available on client.User() when the client has no authtoken.

Method NameReturnsDescription
ForgotPasswordThe password reset request result.Emails a reset token to the account.
ForgotPasswordAsyncThe password reset request result.Emails a reset token asynchronously.
ResetPasswordThe password reset result.Sets a new password with the reset token.
ResetPasswordAsyncThe password reset result.Sets a new password asynchronously.

Class-Level Snippet

This snippet requests a reset email, then sets a new password with the token from that email.

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;

ContentstackClient client = new ContentstackClient();
User user = client.User();

try
{
    await user.ForgotPasswordAsync("<EMAIL>");
    Console.WriteLine("Paste the reset token from the email:");

    string resetToken = Console.ReadLine() ?? "";
    ContentstackResponse response = await user.ResetPasswordAsync(resetToken, "<NEW_PASSWORD>", "<NEW_PASSWORD>");
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

Methods

Each method of the User class has its own section below, with its parameters, validation rules, behavior, and examples.

ForgotPassword

ForgotPassword asks the API to email a password reset token to a Contentstack account.

NameTypeDescription
email (required)string

Email address of the account.

Default: Not applicable

Returns: ContentstackResponse. The password reset request result.

Validation

  • Throws InvalidOperationException if the client has an authtoken, because the request is for a user who cannot sign in.
  • Throws ArgumentNullException (parameter email) if email is null or empty.
  • The SDK does not check the email format. An address the API does not accept fails there.
  • Throws ContentstackErrorException when the API rejects the request.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • ForgotPassword sends one POST /user/forgot_password request, the Request for a password request of the Content Management API (CMA), with the body {"user": {"email": ...}}.
  • The API emails a reset token to the address. Pass that token to ResetPassword.
  • Returns the raw API response.

Example

Basic usage: request a reset email

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient();

try
{
    ContentstackResponse response = client.User().ForgotPassword("<EMAIL>");
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

Edge case: a client that has an authtoken

using System;
using Contentstack.Management.Core;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    client.User().ForgotPassword("<EMAIL>");
}
catch (InvalidOperationException e)
{
    // Fires before any request, because the client holds an authtoken
    Console.WriteLine(e.Message);
}

ForgotPasswordAsync

ForgotPasswordAsync asks the API to email a password reset token to a Contentstack account, without blocking the calling thread.

NameTypeDescription
email (required)string

Email address of the account.

Default: Not applicable

Returns: Task<ContentstackResponse>. The password reset request result.

Validation

  • Throws InvalidOperationException if the client has an authtoken, and ArgumentNullException if email is null or empty. The SDK throws both when you call ForgotPasswordAsync, before it returns a task.
  • Throws ContentstackErrorException when you await the task and the API rejects the request.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

Example

Basic usage: request a reset email

using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient();

try
{
    ContentstackResponse response = await client.User().ForgotPasswordAsync("<EMAIL>");
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

Edge case: an empty email

using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;

ContentstackClient client = new ContentstackClient();

try
{
    await client.User().ForgotPasswordAsync("");
}
catch (ArgumentNullException e)
{
    // Fires before any request, because the email is empty
    Console.WriteLine(e.ParamName);
}

ResetPassword

ResetPassword sets a new password for a Contentstack account with the reset token from the reset email.

NameTypeDescription
resetToken (required)string

Token from the reset email.

Default: Not applicable
password (required)string

New password.

Default: Not applicable
confirmPassword (required)string

New password again, for confirmation.

Default: Not applicable

Returns: ContentstackResponse. The password reset result.

Validation

  • Throws InvalidOperationException if the client has an authtoken, because the request is for a user who cannot sign in.
  • Throws ArgumentNullException if resetToken, password, or confirmPassword is null or empty. ParamName names the empty argument.
  • The SDK does not compare password with confirmPassword, and does not check password rules. The API rejects a mismatch or a weak password.
  • Throws ContentstackErrorException when the API rejects the request, for example for an expired token.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • ResetPassword sends one POST /user/reset_password request, the Reset password request of the Content Management API (CMA), with the body {"user": {"reset_password_token": ..., "password": ..., "password_confirmation": ...}}.
  • Get the token by calling ForgotPassword first.
  • Returns the raw API response. ResetPassword does not sign in. Call Login with the new password afterward.

Example

Basic usage: set a new password

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient();

try
{
    ContentstackResponse response = client.User().ResetPassword("<RESET_PASSWORD_TOKEN>", "<NEW_PASSWORD>", "<NEW_PASSWORD>");
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

Edge case: an empty confirmation

using System;
using Contentstack.Management.Core;

ContentstackClient client = new ContentstackClient();

try
{
    client.User().ResetPassword("<RESET_PASSWORD_TOKEN>", "<NEW_PASSWORD>", "");
}
catch (ArgumentNullException e)
{
    // Fires before any request. Prints confirmPassword.
    Console.WriteLine(e.ParamName);
}

ResetPasswordAsync

ResetPasswordAsync sets a new password for a Contentstack account with the reset token, without blocking the calling thread.

NameTypeDescription
resetToken (required)string

Token from the reset email.

Default: Not applicable
password (required)string

New password.

Default: Not applicable
confirmPassword (required)string

New password again, for confirmation.

Default: Not applicable

Returns: Task<ContentstackResponse>. The password reset result.

Validation

  • Throws InvalidOperationException if the client has an authtoken, and ArgumentNullException if an argument is null or empty. The SDK throws both when you call ResetPasswordAsync, before it returns a task.
  • Throws ContentstackErrorException when you await the task and the API rejects the request.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

Example

Basic usage: set a new password

using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient();

try
{
    ContentstackResponse response = await client.User().ResetPasswordAsync("<RESET_PASSWORD_TOKEN>", "<NEW_PASSWORD>", "<NEW_PASSWORD>");
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

Edge case: sign in with the new password

using System;
using System.Net;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient();

try
{
    await client.User().ResetPasswordAsync("<RESET_PASSWORD_TOKEN>", "<NEW_PASSWORD>", "<NEW_PASSWORD>");

    // ResetPasswordAsync does not sign in, so log in with the new password.
    await client.LoginAsync(new NetworkCredential("<EMAIL>", "<NEW_PASSWORD>"));
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}