split invite and user session management, add createSessionToken docs

docs/reference/engine/tenant/users.md → docs/reference/engine/tenant/invites.md

@@ -1,67 +1,9 @@
 ---
-title: User management
+title: User invitations
 ---
 
-## Sign in
-
-For sign in, you need a [login token](overview.md#authorization-tokens). After successful login, you receive a session token for subsequent requests.
-
-
-#### Example: sign in
-```graphql
-mutation {
-  signIn(email: "admin@example.com", password: "123456", expiration: 3600) {
-    ok
-    result {
-      token
-    }
-    error {
-      code
-    }
-  }
-}
-```
-
-:::note
-Expiration is automatically extended after each request.
-:::
-
-## Sign out
-
-By calling `signOut` mutation, you can invalidate a token associated with current request
-
-
-#### Example: sign out current session
-```graphql
-mutation {
-  signOut {
-    ok
-  }
-}
-```
-
-By setting a parameter `all` to `true`, you invalidate all tokens associated with a current identity. 
-
-#### Example: sign out all sessions
-```graphql
-mutation {
-  signOut(all: true) {
-    ok
-  }
-}
-``` 
-:::note
-Only persons are allowed to sign out. It cannot be called with a permanent API key.
-:::
-
-## Inviting Users to a Project
-
 The `invite` mutation provides a way to add a new member to a specified project within the system.
 
-### Invite permissions
-
-By default, users with the global roles `super_admin` and `project_admin`, along with project-level `admin`, are authorized to issue invitations. However, you can extend this capability to other user roles by configuring [Tenant ACL permissions](/reference/engine/schema/acl.md#tenant-permissions).
-
 #### Example: sending and invitation
 
 ```graphql
@@ -88,6 +30,10 @@ mutation {
 }
 ```
 
+### Invite permissions
+
+By default, users with the global roles `super_admin` and `project_admin`, along with project-level `admin`, are authorized to issue invitations. However, you can extend this capability to other user roles by configuring [Tenant ACL permissions](/reference/engine/schema/acl.md#tenant-permissions).
+
 ### Existing vs new users
 
 If the specified email address already corresponds to a user in the system, that user will simply be added to the designated project. If the user does not yet exist, a new account will be created, and login instructions will be sent to the provided email address.

docs/reference/engine/tenant/mail-templates.md

@@ -87,7 +87,7 @@ Contember uses Mustache for dynamic content in templates. Here are the variables
   - `{{password}}`: Password (if available).
   - `{{token}}`: Token for account validation (if available).
   - `{{project}}`: Project name or identifier.
-  - availability of `password` and `token` variable depends on [invitation method](./users.md#password-handling)
+  - availability of `password` and `token` variable depends on [invitation method](./invites.md#password-handling)
 
 - **EXISTING_USER_INVITED**:
   - `{{email}}`: Recipient's email.

docs/reference/engine/tenant/memberships.md

@@ -6,7 +6,7 @@ An identity can be a member of any project with some role and optionally variabl
 
 ## Creating a project membership
 
-Add an existing identity to a project. For this operation you need to know an identity ID. If you want to add a user by an email check [invite mutation](users.md#invite)
+Add an existing identity to a project. For this operation you need to know an identity ID. If you want to add a user by an email check [invite mutation](./invites.md)
 
 ```graphql
 mutation {

docs/reference/engine/tenant/sessions.md

@@ -0,0 +1,83 @@
+---
+title: User Sessions
+---
+
+User session management is a crucial aspect of maintaining secure and efficient interactions within your application. This guide elaborates on how to manage user sessions through sign-ins and sign-outs using Contember's Tenant API.
+
+## Sign In to Your Account
+
+To sign in, you need a [login token](overview.md#authorization-tokens). Once you've successfully signed in, a session token will be issued, which is necessary for making subsequent authenticated requests.
+
+#### Example: How to Sign In
+
+```graphql
+mutation {
+  signIn(email: "admin@example.com", password: "123456", expiration: 3600) {
+    ok
+    result {
+      token
+    }
+    error {
+      code
+    }
+  }
+}
+```
+
+:::note
+The session token's expiration time will be automatically extended with each subsequent request you make, so you don't need to worry about frequent re-logins.
+:::
+
+## Sign Out of Your Account
+
+Signing out is straightforward: all you need to do is call the `signOut` mutation. This invalidates the session token associated with the current request, effectively logging you out.
+
+#### Example: How to Sign Out from the Current Session
+
+```graphql
+mutation {
+  signOut {
+    ok
+  }
+}
+```
+
+### Signing Out of All Sessions
+
+If you want to take an extra step in security or think your credentials have been compromised, you can invalidate all session tokens associated with your current identity by setting the `all` parameter to `true`.
+
+#### Example: How to Sign Out from All Sessions
+
+```graphql
+mutation {
+  signOut(all: true) {
+    ok
+  }
+}
+``` 
+
+:::note
+Keep in mind that the `signOut` mutation is only applicable for persons (users with a set of credentials). It cannot be called using a permanent API key. This design choice ensures that application-level permissions remain secure.
+:::
+
+## Advanced: Create session token manually
+
+For users with `super_admin` or `project_admin` roles, the `createSessionToken` mutation provides a way to generate session tokens for other users. This functionality enables administrators to act as a specific user.
+
+### Example: Create session token for given user
+
+```graphql
+mutation {
+  createSessionToken(email: "example@email.com", expiration: 3600) {
+    ok
+    result {
+      token
+    }
+    error {
+      code
+    }
+  }
+}
+```
+
+You must supply either an `email` or a `personId`, along with an optional expiration time for the token.

sidebars.js

@@ -194,7 +194,8 @@ module.exports = {
 					label: "Tenant API",
 					items: [
 						"reference/engine/tenant/overview",
-						"reference/engine/tenant/users",
+						"reference/engine/tenant/sessions",
+						"reference/engine/tenant/invites",
 						"reference/engine/tenant/memberships",
 						"reference/engine/tenant/api-keys",
 						"reference/engine/tenant/idp",