docs(api-admin): add get registered user method| openapi docs

docs(api-admin): fix path

docs(api-admin): fix review comments

docs(api-admin): fix review comments

docs(api-admin): fix error description

Create linear-linker.yml

docs(api-admin): add add-user method description | openapi docs (#37)

fix(api-admin): naming, remove example method

merged manually #39

Closes #39

fix

docs(api-admin): add delete user method description | openapi docs (#36)

* docs(api-admin): add delete user method description | openapi docs

* docs(api-admin): fix review comments

* docs(api-admin): fix review

* docs(api-admin): typo fixes

* docs(api-admin): fix error description

Apply suggestions from code review

.github/workflows/linear-linker.yml

@@ -0,0 +1,17 @@
+name: Linear.app Linker
+
+on:
+  pull_request:
+    types: [opened, closed, reopened, synchronize, ready_for_review]
+
+jobs:
+  linear_linker:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: cardbox/linear-action@v0
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          linear-token: ${{ secrets.LINEAR_TOKEN }}
+          issue-prefixes: ACC BOX EDI META CAP
+          state-map: drafted = In Progress; ready = In Review; merged = Done; closed = Todo

api-admin/openapi.yaml

@@ -9,127 +9,273 @@ servers:
   - url: http://localhost:9020/
   - url: https://accesso.sova.dev/api/admin
 paths:
-  "/oauth/authorize":
+  "/applications/user.add":
     post:
-      operationId: oauthAuthorizeRequest
-      tags: [ OAuth ]
-      description: Authorization request
+      operationId: applicationsUserAdd
+      tags: [ Applications ]
+      description: Add user to application
       requestBody:
-        $ref: "#/components/requestBodies/OAuthAuthorize"
+        $ref: "#/components/requestBodies/ApplicationsUserAdd"
       responses:
         200:
-          $ref: "#/components/responses/OAuthAuthorizeDone"
+          $ref: "#/components/responses/ApplicationsUserAddSuccess"
         400:
-          $ref: "#/components/responses/OAuthAuthorizeRequestFailure"
+          $ref: "#/components/responses/ApplicationsUserAddFailure"
         500:
-          description: Something goes wrong
+          description: Something went wrong
+
+  "/applications/secret.regenerate":
+    post:
+      operationId: applicationsSecretRegenerate
+      tags: [ Applications ]
+      description: create new secret key
+      requestBody:
+        $ref: "#/components/requestBodies/ApplicationsSecretRegenerate"
+      responses:
+        200:
+          $ref: "#/components/responses/ApplicationsSecretRegenerateSuccess"
+        400:
+          $ref: "#/components/responses/ApplicationsSecretRegenerateFailure"
+        500:
+          description: Something went wrong
+
+  "/applications/user.remove":
+    post:
+      operationId: applicationsUserRemove
+      tags: [ Applications ]
+      description: Remove user from application
+      requestBody:
+        $ref: "#/components/requestBodies/ApplicationsUserRemove"
+      responses:
+        200:
+          $ref: "#/components/responses/ApplicationsUserRemoveSuccess"
+        400:
+          $ref: "#/components/responses/ApplicationsUserRemoveFailure"
+        500:
+          description: Something went wrong
+
+  "/applications/users.list":
+    post:
+      operationId: applicationsUsersList
+      tags: [ Users ]
+      description: Get all registered users
+      requestBody:
+        $ref: "#/components/requestBodies/ApplicationsUsersList"
+      responses:
+        200:
+          $ref: "#/components/responses/ApplicationsUsersListSuccess"
+        400:
+          $ref: "#/components/responses/ApplicationsUsersListFailure"
+        500:
+          description: Something went wrong
 
 components:
   responses:
-    OAuthAuthorizeDone:
-      description: Authorization completed, now access token can be obtained.
+    ApplicationsUserAddSuccess:
+      description: User was added successful.
+      content:
+        application/json:
+          schema:
+            type: object
+
+    ApplicationsUserAddFailure:
+      description:
+        Happens when something went wrong after attemp to connect user with application
       content:
         application/json:
           schema:
             required:
-              - redirectUri
               - code
             properties:
-              redirectUri:
-                description: User should be redirected to
-                type: string
-                format: url
               code:
-                description: This parameter contains the authorization code which the client will later exchange for an access token.
+                description: |
+                  Possible errors: <br/>
+                  `access_denied` — This error occures when user's session was expired | user doesn't have enough permission | or user unauthorized.<br/>
+                  `invalid_request` — Something was wrong with user request.<br/>
+                  `application_not_found` — Occure when application_id was not found.<br/>
+                  `user_not_found` — Occure when user_id was not found.<br/>
                 type: string
-              state:
-                description:
-                  If the initial request contained a state parameter, the response must also include the exact value from the request.
-                  The client will be using this to associate this response with the initial request.
+                enum:
+                  - access_denied
+                  - invalid_request
+                  - application_not_found
+                  - user_not_found
+
+    ApplicationsSecretRegenerateSuccess:
+      description: New app secret was generated.
+      content:
+        application/json:
+          schema:
+            required:
+              - secretKey
+            properties:
+              secretKey:
+                description: New secret key
                 type: string
+                example: 41190cee52314dcc8167_ebf798b55ce3
 
-    OAuthAuthorizeRequestFailure:
+    ApplicationsSecretRegenerateFailure:
       description:
-        There are two different kinds of errors to handle. The first kind of error is when the developer did something wrong when creating the authorization request. The other kind of error is when the user rejects the request (clicks the “Deny” button).
-        <br/>
-        If there is something wrong with the syntax of the request, such as the redirect_uri or client_id is invalid, then it’s important not to redirect the user and instead you should show the error message directly. This is to avoid letting your authorization server be used as an open redirector.
-        <br/>
-        If the redirect_uri and client_id are both valid, but there is still some other problem, it’s okay to redirect the user back to the redirect URI with the error in the query string.
+        Happens when something went wrong after attemp to regenerate application key
       content:
         application/json:
           schema:
             required:
-              - error
+              - code
             properties:
-              error:
+              code:
                 description: |
                   Possible errors: <br/>
-                  If the user denies the authorization request, the server will redirect the user back to the redirect URL with error=`access_denied` in the query string, and no code will be present. It is up to the app to decide what to display to the user at this point.<br/>
-                  `invalid_request` — The request is missing a required parameter, includes an invalid parameter value, or is otherwise malformed.<br/>
-                  `unsupported_response_type` — The authorization server does not support obtaining an authorization code using this method.<br/>
-                  `invalid_scope` — The requested scope is invalid, unknown, or malformed.<br/>
-                  `server_error` — The authorization server encountered an unexpected condition which prevented it from fulfilling the request.<br/>
-                  `temporarily_unavailable` — The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server.<br/>
-                  [OAuth2 Possible Errors](https://www.oauth.com/oauth2-servers/server-side-apps/possible-errors/)
+                  `access_denied` -- This error occures when user's session was expired | user doesn't have enough permission | or user unauthorized.<br/>
+                  `invalid_request` -- Something was wrong with user request.<br/>
                 type: string
                 enum:
                   - access_denied
                   - invalid_request
-                  - invalid_scope
-                  - server_error
-                  - temporarily_unavailable
-                  - unauthenticated_user
-                  - unauthorized_client
-                  - unsupported_response_type
-              redirectUri:
-                description: User should be redirected to if passed redirectUri and clientId is correct
+
+    ApplicationsUserRemoveSuccess:
+      description: User was deleted successful.
+      content:
+        application/json:
+          schema:
+            type: object
+
+    ApplicationsUserRemoveFailure:
+      description:
+        Happens when something went wrong after attemp to delete application
+      content:
+        application/json:
+          schema:
+            required:
+              - code
+            properties:
+              code:
+                description: |
+                  Possible errors: <br/>
+                  `access_denied` — This error occures when user's session was expired | user doesn't have enough permission | or user unauthorized.<br/>
+                  `invalid_request` — Something was wrong with user request.<br/>
+                  `application_not_found` — Occure when application_id was not found.<br/>
+                  `user_not_found` — Occure when user_id was not found.<br/>
                 type: string
-                format: url
-              state:
-                description:
-                  If the initial request contained a state parameter, the response must also include the exact value from the request.
-                  The client will be using this to associate this response with the initial request.
+                enum:
+                  - access_denied
+                  - invalid_request
+                  - application_not_found
+                  - user_not_found
+
+    ApplicationsUsersListSuccess:
+      description: Get registered users
+      content:
+        application/json:
+          schema:
+            type: object
+            required:
+              - users
+            properties:
+              users:
+                type: array
+                items:
+                  $ref: '#/components/schemas/User'
+
+    ApplicationsUsersListFailure:
+      description:
+        Happens when something went wrong after attemp to get registered users list
+      content:
+        application/json:
+          schema:
+            required:
+              - code
+            properties:
+              code:
+                description: |
+                  Possible errors: <br/>
+                  `access_denied` — This error occures when user's session was expired | user doesn't have enough permission | or user unauthorized.<br/>
+                  `application_not_found` — No application with provided ID.<br/>
                 type: string
+                enum:
+                  - access_denied
+                  - application_not_found
 
   requestBodies:
-    OAuthAuthorize:
+    ApplicationsUsersAdd:
       required: true
       content:
         application/json:
           schema:
             required:
-              - responseType
-              - clientId
-              - redirectUri
+              - applicationId
+              - userId
             properties:
-              responseType:
-                description: responseType is set to code indicating that you want an authorization code as the response.
+              applicationId:
+                description: The identifier of application.
                 type: string
-                enum: [ code ]
-              clientId:
-                description: The clientId is the identifier for your app.
-                  You will have received a clientId when first registering your app with the service.
+                format: uuid
+                example: 41190cee-5231-4dcc-8167-ebf798b55ce3
+              userId:
                 type: string
                 format: uuid
                 example: 41190cee-5231-4dcc-8167-ebf798b55ce3
-              redirectUri:
-                description: |
-                  The redirectUri may be optional depending on the API, but is highly recommended.<br/>
-                  This is the URL to which you want the user to be redirected after the authorization is complete.<br/>
-                  This must match the redirect URL that you have previously registered with the service.<br/>
+
+    ApplicationsSecretRegenerate:
+      required: true
+      content:
+        application/json:
+          schema:
+            required:
+              - applicationId
+            properties:
+              applicationId:
+                description: ID if the application need to regenerate the secret key.
                 type: string
-                format: uri
-                example: https://example-app.com/oauth/callback
-              scope:
-                description: Include one or more scope values (space-separated) to request additional levels of access.<br/>
+                format: uuid
+                example: 41190cee-5231-4dcc-8167-ebf798b55ce3
+
+    ApplicationsUserRemove:
+      required: true
+      content:
+        application/json:
+          schema:
+            required:
+              - applicationId
+              - userId
+            properties:
+              applicationId:
+                description: The identifier of your app.
                 type: string
-                example: "user:view user:edit"
-              state:
-                description: The state parameter serves two functions.<br/>
-                  When the user is redirected back to your app, whatever value you include as the state will also be included in the redirect.<br/>
-                  This gives your app a chance to persist data between the user being directed to the authorization server and back again,
-                  such as using the state parameter as a session key. This may be used to indicate what action in the app to perform after authorization is complete,
-                  for example, indicating which of your app’s pages to redirect to after authorization. This also serves as a CSRF protection mechanism.<br/>
-                  When the user is redirected back to your app, double check that the state value matches what you set it to originally.
-                  This will ensure an attacker can’t intercept the authorization flow.
+                format: uuid
+                example: 41190cee-5231-4dcc-8167-ebf798b55ce3
+              userId:
                 type: string
+                format: uuid
+                example: 41190cee-5231-4dcc-8167-ebf798b55ce3
+
+    ApplicationsUsersList:
+      required: true
+      content:
+        application/json:
+          schema:
+            required:
+              - applicationId
+            properties:
+              applicationId:
+                type: string
+                format: uuid
+                example: 41190cee-5231-4dcc-8167-ebf798b55ce3
+
+  schemas:
+    User:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        firstName:
+          type: string
+          example: John
+        lastName:
+          type: string
+          example: Doe
+        email:
+          type: string
+          format: email
+          example: [email protected]