Docs/public signup (#2070)

* update snapshot

* add api doc

* describe api

* reference initial

* updated public signup api docs
created public invite api docs

* docs

* docs update

* docs update

* add description to openapi endpoints

* add description to openapi endpoints

* fix snapshot

* Update src/lib/openapi/spec/public-signup-token-create-schema.ts

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>

* Update src/lib/openapi/spec/public-signup-token-schema.ts

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>

* Update src/lib/routes/admin-api/public-signup.ts

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>

* Update src/lib/routes/public-invite.ts

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>

* Update src/lib/openapi/spec/public-signup-token-schema.ts

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>

* Update src/lib/routes/admin-api/public-signup.ts

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>

* Update website/docs/reference/public-signup.mdx

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>

* PR comments

* delete api docs

* fix snapshot

* Update src/lib/routes/admin-api/public-signup.ts

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>

* bug fix

* bug fix

* bug fix

* Update src/lib/openapi/spec/public-signup-token-create-schema.ts

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>

* Update src/lib/openapi/spec/public-signup-token-schema.ts

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>

* Update src/lib/openapi/spec/public-signup-token-update-schema.ts

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>

* Update src/lib/routes/admin-api/public-signup.ts

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>

* Update src/lib/routes/admin-api/public-signup.ts

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>

* Update src/lib/routes/public-invite.ts

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>

* bug fix

* fix links

* update snapshot

* update snapshot

Co-authored-by: Thomas Heartman <thomas@getunleash.ai>

src/lib/openapi/spec/public-signup-token-create-schema.ts

@@ -7,10 +7,12 @@ export const publicSignupTokenCreateSchema = {
     required: ['name', 'expiresAt'],
     properties: {
         name: {
+            description: `The token's name.`,
             type: 'string',
         },
         expiresAt: {
             type: 'string',
+            description: `The token's expiration date.`,
             format: 'date-time',
         },
     },

src/lib/openapi/spec/public-signup-token-schema.ts

@@ -45,7 +45,7 @@ export const publicSignupTokenSchema = {
         },
         users: {
             type: 'array',
-            description: 'Array of users that have signed up using the token',
+            description: 'Array of users that have signed up using the token.',
             items: {
                 $ref: '#/components/schemas/userSchema',
             },

src/lib/openapi/spec/public-signup-token-update-schema.ts

@@ -7,6 +7,7 @@ export const publicSignupTokenUpdateSchema = {
     properties: {
         expiresAt: {
             type: 'string',
+            description: `The token's expiration date.`,
             format: 'date-time',
         },
         enabled: {

src/lib/routes/admin-api/public-signup.ts

@@ -72,6 +72,7 @@ export class PublicSignupController extends Controller {
             middleware: [
                 openApiService.validPath({
                     tags: ['Public signup tokens'],
+                    summary: 'Retrieve all existing public signup tokens',
                     operationId: 'getAllPublicSignupTokens',
                     responses: {
                         200: createResponseSchema('publicSignupTokensSchema'),
@@ -89,6 +90,7 @@ export class PublicSignupController extends Controller {
                 openApiService.validPath({
                     tags: ['Public signup tokens'],
                     operationId: 'createPublicSignupToken',
+                    summary: 'Create a public signup token',
                     requestBody: createRequestSchema(
                         'publicSignupTokenCreateSchema',
                     ),
@@ -109,6 +111,9 @@ export class PublicSignupController extends Controller {
             middleware: [
                 openApiService.validPath({
                     tags: ['Public signup tokens'],
+                    summary: 'Retrieve a token',
+                    description:
+                        "Get information about a specific token. The `:token` part of the URL should be the token's secret.",
                     operationId: 'getPublicSignupToken',
                     responses: {
                         200: createResponseSchema('publicSignupTokenSchema'),
@@ -126,6 +131,7 @@ export class PublicSignupController extends Controller {
                 openApiService.validPath({
                     tags: ['Public signup tokens'],
                     operationId: 'updatePublicSignupToken',
+                    summary: 'Update a public signup token',
                     requestBody: createRequestSchema(
                         'publicSignupTokenUpdateSchema',
                     ),

src/lib/routes/public-invite.ts

@@ -14,7 +14,6 @@ import {
     getStandardResponses,
 } from '../openapi/util/standard-responses';
 import { PublicSignupTokenService } from '../services/public-signup-token-service';
-import { PublicSignupTokenSchema } from '../openapi/spec/public-signup-token-schema';
 import { UserSchema, userSchema } from '../openapi/spec/user-schema';
 import { CreateInvitedUserSchema } from '../openapi/spec/create-invited-user-schema';
 
@@ -53,7 +52,7 @@ export class PublicInviteController extends Controller {
                 openApiService.validPath({
                     tags: ['Public signup tokens'],
                     operationId: 'validatePublicSignupToken',
-                    summary: `Validates a public signup token exists, has not expired and is enabled`,
+                    summary: `Check whether a public sign-up token exists, has not expired and is enabled`,
                     responses: {
                         200: emptyResponse,
                         ...getStandardResponses(400),
@@ -85,7 +84,7 @@ export class PublicInviteController extends Controller {
 
     async validate(
         req: IAuthRequest<TokenParam, void>,
-        res: Response<PublicSignupTokenSchema>,
+        res: Response,
     ): Promise<void> {
         const { token } = req.params;
         const valid = await this.publicSignupTokenService.validate(token);

src/test/e2e/api/admin/project/features.e2e.test.ts

@@ -43,6 +43,8 @@ afterEach(async () => {
                 ),
             ),
     );
+
+    await db.stores.strategyStore.deleteAll();
 });
 
 afterAll(async () => {

src/test/e2e/api/openapi/__snapshots__/openapi.e2e.test.ts.snap

@@ -2450,10 +2450,12 @@ exports[`should serve the OpenAPI spec 1`] = `
         "additionalProperties": false,
         "properties": {
           "expiresAt": {
+            "description": "The token's expiration date.",
             "format": "date-time",
             "type": "string",
           },
           "name": {
+            "description": "The token's name.",
             "type": "string",
           },
         },
@@ -2496,7 +2498,7 @@ exports[`should serve the OpenAPI spec 1`] = `
             "type": "string",
           },
           "users": {
-            "description": "Array of users that have signed up using the token",
+            "description": "Array of users that have signed up using the token.",
             "items": {
               "$ref": "#/components/schemas/userSchema",
             },
@@ -2523,6 +2525,7 @@ exports[`should serve the OpenAPI spec 1`] = `
             "type": "boolean",
           },
           "expiresAt": {
+            "description": "The token's expiration date.",
             "format": "date-time",
             "type": "string",
           },
@@ -4585,6 +4588,7 @@ If the provided project does not exist, the list of events will be empty.",
             "description": "publicSignupTokensSchema",
           },
         },
+        "summary": "Retrieve all existing public signup tokens",
         "tags": [
           "Public signup tokens",
         ],
@@ -4623,6 +4627,7 @@ If the provided project does not exist, the list of events will be empty.",
             },
           },
         },
+        "summary": "Create a public signup token",
         "tags": [
           "Public signup tokens",
         ],
@@ -4630,6 +4635,7 @@ If the provided project does not exist, the list of events will be empty.",
     },
     "/api/admin/invite-link/tokens/{token}": {
       "get": {
+        "description": "Get information about a specific token. The \`:token\` part of the URL should be the token's secret.",
         "operationId": "getPublicSignupToken",
         "parameters": [
           {
@@ -4653,6 +4659,7 @@ If the provided project does not exist, the list of events will be empty.",
             "description": "publicSignupTokenSchema",
           },
         },
+        "summary": "Retrieve a token",
         "tags": [
           "Public signup tokens",
         ],
@@ -4692,6 +4699,7 @@ If the provided project does not exist, the list of events will be empty.",
             "description": "publicSignupTokenSchema",
           },
         },
+        "summary": "Update a public signup token",
         "tags": [
           "Public signup tokens",
         ],
@@ -7505,7 +7513,7 @@ If the provided project does not exist, the list of events will be empty.",
             "description": "The request data does not match what we expect.",
           },
         },
-        "summary": "Validates a public signup token exists, has not expired and is enabled",
+        "summary": "Check whether a public sign-up token exists, has not expired and is enabled",
         "tags": [
           "Public signup tokens",
         ],

website/.gitignore

@@ -20,6 +20,6 @@ yarn-debug.log*
 yarn-error.log*
 
 # OpenAPI docusaurus generated stuff
-docs/reference/apis/**/sidebar.js
+docs/reference/api/**/sidebar.js
 *.api.mdx
 *.tag.mdx

website/docs/how-to/how-to-manage-public-invite-tokens.mdx

@@ -0,0 +1,26 @@
+---
+title: How to manage public invite tokens
+---
+
+[Public invite links](../reference/public-signup.mdx) let you invite new members to an Unleash instance. A key part of an invite link is the public invite token. This guide shows you how to use the Unleash admin UI to create, update, and delete public invite tokens. You can also [manage public signup tokens via the Unleash API](../reference/api/unleash/public-signup-tokens.tag.mdx).
+
+Only Unleash instance admins have the necessary permissions to create and manage public invite tokens.
+
+## Creating a token
+
+1. Navigate to the **users** page in Unleash and use the **create invite link** button
+
+![The settings menu in the Unleash nav bar with the "users" link highlighted.](/img/public-signup-step1.png)
+
+![The Unleash users page. There is a separate "create invite link" section above the list of users.](/img/public-signup-step2.png)
+
+2. Fill out the "create invite link" form and (optionally) copy the invite link. You can always get the link later.
+![A short form with only one field: token expiry.](/img/public-signup-step3-create_link.png)
+
+![An "invite link created" modal. It contains an invite link that can be copied and some info on how to use it.](/img/public-signup-step4_link_Created.png)
+
+## Updating/Deleting a token
+
+1. Follow the steps in [the previous paragraph](#creating-a-token) to navigate to the users page.
+2. When you have an active invite token, use the button labeled "update invite link".
+3. Use the form to edit the expiry for the token or to delete it entirely.

website/docs/reference/public-signup.mdx

@@ -0,0 +1,26 @@
+---
+title: Public Invite Links
+---
+
+Public invite links let you invite team members to your Unleash instance. Any user with an invite link can sign up to Unleash instance that created the link. The user will get the **viewer** role (refer to the [_standard roles_ section of the RBAC document](../user_guide/rbac.md#standard-roles) for more information on roles).
+
+User who follow the invite link are taken directly to the Unleash sign-up page, where they can create an account.
+
+Only **Unleash instance admins** can create public invite links.
+
+![An Unleash signup form for new users](/img/public-invite_signup.png)
+
+## Public sign-up tokens
+
+The most important part of a public sign-up link is the sign-up token. The token is added as the `invite` query parameter to the invite link.
+
+Each token has an **expiry date**. After this expiry date, the token will stop working and users can no longer sign up using an invite link with that token.
+
+## Creating, updating, and deleting tokens
+
+You can [create, update and delete tokens via the Unleash Admin UI](../how-to/how-to-manage-public-invite-tokens.mdx) or via the [Unleash API](../reference/api/unleash/public-signup-tokens.tag.mdx "Public sign-up tokens API documentation").
+
+A token is active as soon as it's created and stops working as soon as it's deleted or expired.
+
+You can only have one active invite token at a time. If you already have an active token, you must delete it to create a new one.
+

website/sidebars.js

@@ -289,6 +289,7 @@ module.exports = {
                         'advanced/toggle_variants',
                         'reference/front-end-api',
                         'reference/playground',
+                        'reference/public-signup',
                         'user_guide/projects',
                         'user_guide/rbac',
                         'reference/segments',