Own backend processing

For each endpoint, you can specify which token is required to access it in the app options.

By default, all endpoints can be accessed using the public token, except for "register" and "user delete", which require the secret token. For more information, please refer to the "Create an app" documentation.

This feature provides flexibility for storing additional user data in your own backend while only sending necessary data to the sentc backend.

In general, every main function in sentc has two equivalent functions with a prepare and done prefix.

Example

import Sentc from "@sentclose/sentc";

const user_id = await Sentc.register("username", "password");

//no promise here
//call this before you do the request to your backend
const input = Sentc.prepareRegister("username", "password");

//call this after you call the api. in the client
const user_id = Sentc.doneRegister("server_output");

Example

//call this before you do the request to your backend
final input = await Sentc.prepareRegister("username", "password");

//call this after you call the api. in the client
final userId = await Sentc.doneRegister("server_output");

To retrieve the necessary server input for your API, call the prepare function in the client. Once you have this input, make a request to your own backend API using the secret token provided by sentc.

Response

The response from our api is always structured the same. It is in json format.

Successfully response:

{
	"status": true,
	"result": "<a message or the fetched values>"
}

Failed responses:

{
	"status": false,
	"err_msg": "<text of the error message from the api>",
	"err_code": 0 //api error code as number
}

The done functions will check every server response like this to get the right result.

Authentification

For some requests a jwt is needed. Just pass the jwt in Authorization header as Bearer token.

Header name: Authorization
Header value: Bearer <the_jwt>

App token

For every request, you must send your app token. The sdk will send your public app token automatically. Send it with an x-sentc-app-token header:

Header name: x-sentc-app-token
Header value: <your_app_token>

Use your public token for every frontend related requests and your secret token only for requests from your backend.

User

TIP

The default app settings for user register are from another backend because sentc won't save other data then the keys and the username.

There is no need for an auth header for registration and login.

Register

When creating an account, call the prepare function and send the input string to our api to the endpoint with a post request: https://api.sentc.com/api/v1/register

import Sentc from "@sentclose/sentc";
//call this before you do the request to your backend
const input = Sentc.prepareRegister("username", "password");

//call this before you do the request to your backend
final input = await Sentc.prepareRegister("username", "password");

After your user registration call this function in the client, to check the response:

import Sentc from "@sentclose/sentc";

const user_id = Sentc.doneRegister("server_output");

WARNING

This function will throw an error if the server output is not correct.

//call this after you call the api. in the client
final userId = await Sentc.doneRegister("server_output");

WARNING

This function will throw an error if the server output is not correct.

Or simply check the status of the json response in your backend.

Login

Logging in involves multiple requests and data sharing. The recommended approach is to simply log in on the client-side and then call your backend to retrieve additional data. You can verify the JWT token from the user to ensure security.

Alternatively, you can use your own backend's login process and then log in again to the sentc API on the client-side.

The sentc API login is a highly secure process because the user's password never leaves their client device.

Jwt check

You can simply check the jwt from the sentc api with your jwt public key see more at Create an app.

Register device

The "Prepare register device" function is similar to the initial user registration process. However, the validation for device registration is the same as described in the "User" section here.

To register a device, send the necessary input to our API endpoint using a POST request without a JWT at: https://api.sentc.com/api/v1/user/prepare_register_device

import Sentc from "@sentclose/sentc";

const input = Sentc.prepareRegisterDeviceStart("identifier", "password");

final input = await Sentc.prepareRegisterDeviceStart("identifier", "password");

To check in the client if the request was correct, use the done function with the server output:

import Sentc from "@sentclose/sentc";

const input = Sentc.doneRegisterDeviceStart("server_output");

WARNING

This function will throw an error if the server output is not correct.

final input = await Sentc.doneRegisterDeviceStart("server_output");

Group

DANGER

Do not forget to send an Authorization header with the Jwt as Bearer value.

Create group

To create a group, call the "prepare" function from the user object as we need the user keys.

Send the necessary input to this endpoint using a POST request: https://api.sentc.com/api/v1/group

The input should contain all the client-related values needed to create a group, such as group keys and the encrypted group key by the user's public key.

Upon successful API request, the resulting group ID will be returned.

const input = user.prepareGroupCreate();

final input = await user.prepareGroupCreate();

Delete group

To delete a group call this endpoint with the jwt in header and a delete request: https://api.sentc.com/api/v1/group/<group_id>

Check group access

At your backend you can also check if a user got access to a group. Use this endpoint: https://api.sentc.com/api/v1/group/<group_id>/light with a GET request.

The response is either an error with status code 310 or a json object:

{
    "group_id",
    "parent_group_id",
    "rank",
    "created_time",
    "joined_time",
    "is_connected_group",
    "access_by"
}

Access by describes how the user access this group. Either direct, as member of a parent group or from a connected group.

Refreshing the jwt

Like we said in user - Authentification and JWT there are three different strategies to handle the refreshing.

Refresh directly by the sdk

This is the default method. Both the refresh and the jwt are stored in the client. When calling the api and the jwt is invalid this token is used.

Refresh from a cookie

In this scenario, a request is made to your endpoint with the old JWT token included in the Authorization header. To refresh the token, make a PUT request to the refresh endpoint on the sentc API from your backend: https://api.sentc.com/api/v1/refresh. Include the old JWT token in the Authorization Bearer header.

When initializing the client, set the refresh endpoint option to "cookie" in the options.

import Sentc from "@sentclose/sentc";

//init the javascript client
await Sentc.init({
    app_token: "5zMb6zs3dEM62n+FxjBilFPp+j9e7YUFA+7pi6Hi",  // <-- your app token
    refresh: {
        endpoint: 0, // or REFRESH_ENDPOINT.cookie for typescript
        endpoint_url: "<your_endpoint>"
    }
});

<script>
    //init the wasm
    const sentc = window.Sentc.default;

    async function run() {
        await sentc.init({
           app_token: "5zMb6zs3dEM62n+FxjBilFPp+j9e7YUFA+7pi6Hi", // <-- your app token
           refresh: { 
               endpoint: 0,
               endpoint_url: "<your_endpoint>"
           }
        });
    }

    run();
</script>

await Sentc.init(
  appToken: "5zMb6zs3dEM62n+FxjBilFPp+j9e7YUFA+7pi6Hi",
  refreshOptions: RefreshOptions(
    endpoint: RefreshOption.cookie,
    endpointUrl: "<your_endpoint>"
  ),
);

To get the refresh token, just get it from the user object after login. The token won't store in the client, just in the object. Then put the refresh token in a cookie.

Refresh with a function

The sdk won't send any requests for refreshing jwt in this case. Instead, you can define a function to refresh the jwt, maybe do the refresh directly in your backend.

Define a function which returns a promise and get the old jwt.

import Sentc from "@sentclose/sentc";

//init the javascript client
await Sentc.init({
    app_token: "5zMb6zs3dEM62n+FxjBilFPp+j9e7YUFA+7pi6Hi",  // <-- your app token
    refresh: {
        endpoint: 1, // or REFRESH_ENDPOINT.cookie_fn for typescript
        endpoint_fn: (old_jwt: string) => Promise<string>
    }
});

<script>
    //init the wasm
    const sentc = window.Sentc.default;

    async function run() {
        await sentc.init({
           app_token: "5zMb6zs3dEM62n+FxjBilFPp+j9e7YUFA+7pi6Hi", // <-- your app token
           refresh: { 
               endpoint: 1,
               endpoint_fn: (old_jwt) => Promise<string>
           }
        });
    }

    run();
</script>

await Sentc.init(
  appToken: "5zMb6zs3dEM62n+FxjBilFPp+j9e7YUFA+7pi6Hi", // <-- your app token
  refreshOptions: RefreshOptions(
    endpoint: RefreshOption.cookieFn,
    endpointFn: (String oldJwt) {
      //do something with the old jwt
    }
  ),
);

TIP

This are all recommended endpoints to call from your backend, if you need to.

Disable Mfa from server

To disable the Multi-factor auth from your backend for a user call this endpoint: https://api.sentc.com/api/v1/user/forced/disable_otp with a delete request and the following body:

{
	"user_identifier": "<user to disable otp>"
}