Protocol Auth

auth:signup

Overview

Creates an user account in the current Container.

The client calls this action to create a new user account in the container associated with the supplied API key. User account information is supplied by the client in order to uniquely identify the created user for later auth:login action.

After successful creation, the system automatically authenticate the user to the system. This effect is equivalent to having called auth:login action by the system on behalf of the client.

It is possible to use this action to create an anonymous user account. An anonymous user account is an account without a user-friendly identifier given by the user. In this case the email field should be omitted.

Action

auth:signup

Parameters

• api_key (string, required)

• email (string, optional)

  Email address to be associated to the user account, which serves as a unique and user-friendly identifier to the user account.

• password (string, required)

  Password to be used to authenticate the user to the user account. For anonymous user account, the client should generate a random secret on behalf of the user.

Returns

• user_id (string) opaque user identifier for the created user account that is unique to the current database.

  The user identifier is suitable as a record ID for identifying user records for the current user.

• access_token (string) opaque access token for associating subsequent API requests with the newly registered user.

Errors

• email_exists A user account already exists with the specified email address.

auth:login

Overview

Authenticates a user to the previously created user account.

The client calls this action in order to authenticate the current user to a user account that was previously registered. This is required so to obtain the user account identifier as well as the access token for making subsequent API requests.

Authentication maybe required again if an access token is expired or is invalidated.

A user account maybe uniquely identified by email or user_id which the client must specify either one.

Action

auth:login

Parameters:

• api_key (string, required)

• email (string, optional)

  Email address for uniquely identifying the user account to be authenticated.

• user_id (string, optional)

  Opaque user identifier of the user account. This is returned when the user is first created.

• password (string, required)

  Secret supplied by the user to prove that the user owns the user account.

Either specify email or user_id field.

Returns

• user_id (string) opaque user identifier for the user account that is unique to the current database.

  The user identifier is suitable as a record ID for identifying user records for the current user.

• access_token (string) opaque access token for associating subsequent API requests with this user account.

Errors

• credentials_incorrect Either the email address or password is not found in the container

auth:logout

Overview

Invalidate the access token of the current user.

This action is called by the client so that the access token cannot be used to make subsequent authenticated requests. From the user's perspective, the user is logged out from the user account.

This action only has effect to the supplied access token. Hence other access tokens are still valid to make authenticated requests.

If successful, the client should not use the supplied access token to make authenticated requests in the future.

Parameters:

• access_token (string, required)

auth:change

Overview

Change user information of the current user account.

The client calls this action to change user information such as email address and password.

The client should also calls this action to convert an anonymous user account into a standard user account by specifying an email address.

This action was previously named auth:reset_password.

Parameters:

• access_token (string, required)

• current_password (string, required)

  User secret for authenticating the user to the current user account.

• password (string, optional)

  New user secret to be associated to the current user account.

• email (string, optional)

  Email address to be associated to the user account, which serves as a unique and user-friendly identifier to the user account.

Errors

• credentials_incorrect User secret supplied by the user is incorrect.

Discussions

• It should be possible to create user account by other means, such as by connecting through Facebook or other social media networks. This use case is not supported by this request format.

• Should user account be shared across all containers? This allows user to be registered once to login to applications created by different developers, but this may result in confusion as the user has to figure out which email-password pair should be used when logging in to a new app.