About User Token

What is the User Token?

The userToken is a short‑lived, signed credential generated by the ZDK backend that authorizes a client application to open and interact with the User Module:

user.actions.open(userToken);

It contains encoded information about the user — such as their ID, nickname, permissions, and optional metadata — and serves as proof that the user has been authenticated and granted access to the features allowed by your ZDK integration.

How it’s issued

Production – userTokens are generated on your backend by calling the ZDK backend service. Your backend must authenticate with ZDK using your company’s credentials. This process ensures that only trusted servers can create valid userTokens.

Testing / Development – For development purposes, you can use the private API to generate a userToken directly from the client. This API is disabled in production and should only be used in non‑production environments.

How it’s used

Once your client application receives the userToken from your backend (typically after user login), you pass it to the ZDK User Module:

user.actions.open(userToken);

This opens the User Module for the authenticated user.

Creating a userToken

The following example shows how to call the private API to create a userToken. In production, call this from your backend using your company’s API key. For development and testing, you can run it in your frontend to verify your integration without backend setup.

export const createUserToken = () => {
  const opts = {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      'Authorization': `Bearer ${'your-api-key'}`
    },
    body: JSON.stringify({
      arguments: [
        {
          id: window.crypto.randomUUID(),
          avatar: '',
          fullname: '',
          nickname: 'ExampleNickname',
          metadata: {},
          permissions: [100, 200, 300, 400, 500, 600, 700, 800]
        }
      ]
    })
  };
 
  return fetch('https://user.dev.zu.casa/user.tokens.private.v1.Service/Create', opts)
    .then(res => res.json())
    .then(res => {
      return { token: res.tokens[0] as string };
    });
};