keksAccount/public/docs/api.yml

swagger: "2.0"
info:
  description: "API Dokumentation for keksAccount oAuth Service."
  version: "1.0.0"
  title: "KeksAccount"
  contact:
    email: "admin@keks.cloud"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "api.account.keks.cloud"
basePath: "/api/v1"
tags:
  - name: "account"
    description: "The User-Account"
  - name: "user"
    description: "Register and Login to an Account"
  - name: "admin"
    description: "Calls for the Admin users only"
  - name: "apps"
    description: "Information and Actions about Apps"
schemes:
  - "https"
paths:
  /user/register:
    post:
      tags:
        - "user"
      summary: "Register a new Account"
      description: "Possible if registration is enabled or the request contains a valide invide"
      produces:
        - "application/json"
      consumes:
        - "multipart/form-data"
        - "application/json"
      parameters:
        - in: formData
          name: username
          description: "Username for the new User"
          required: true
          type: string
        - in: formData
          name: password
          description: "Password for the new User"
          required: true
          type: string
        - in: formData
          name: mail
          description: "A valide E-Mail adress for the User"
          required: true
          type: string
        - in: formData
          name: invite
          description: "If the user have an invite code to create the account"
          required: false
          type: string
        - in: formData
          name: g-recaptcha-response
          description: "If google recaptcha is enabled for account creation this parameter is requierd"
          required: false
          type: string
      responses:
        200:
          description: "User Account crated"
          schema:
            type: "object"
            properties:
              data:
                $ref: '#/definitions/User'
              success:
                type: "boolean"
                example: true
              msg:
                type: "string"
                example: ""
        400:
          description: "Register disabled, you may can register with an valide invite code"
          schema:
            type: "object"
            properties:
              success:
                type: "boolean"
                example: false
              msg:
                type: "string"
                example: "Registration disabled"
        422:
          description: "Some of the data ar missing or invalide, see data in the response object for details"
          schema:
            type: "object"
            properties:
              data:
                type: "object"
                properties:
                  username:
                    type: array
                    items:
                      type: string
                      example: "The username field is required."
                  password:
                    type: array
                    items:
                      type: string
                      example: "The password field is required."
                  mail:
                    type: array
                    items:
                      type: string
                      example: "The mail field is required."
              success:
                type: "boolean"
                example: false
              msg:
                type: "string"
                example: "The given data was invalid."
  /user/login:
    post:
      tags:
        - "user"
      summary: "Login to an Account with Username/Passwort"
      description: "Login with Passwort for the keksAccount GUI, dont use this in your Application."
      produces:
        - "application/json"
      consumes:
        - "multipart/form-data"
        - "application/json"
      parameters:
        - in: formData
          name: username
          description: "Username"
          required: true
          type: string
        - in: formData
          name: password
          description: "Password"
          required: true
          type: string
      responses:
        200:
          description: "Login succesfull"
          schema:
            type: "object"
            properties:
              data:
                type: "object"
                properties:
                  access_token:
                    type: "string"
                    description: "Access Token for the user"
                  token_type:
                    type: "string"
                    description: "Typ of the Token"
                    example: ""
              success:
                type: "boolean"
                example: true
              msg:
                type: "string"
                example: ""
        400:
          description: "Register disabled, you may can register with an valide invite code"
          schema:
            type: "object"
            properties:
              success:
                type: "boolean"
                example: false
              msg:
                type: "string"
                example: "Registration disabled"
        422:
          description: "Some of the data ar missing or invalide, see data in the response object for details"
          schema:
            type: "object"
            properties:
              data:
                type: "object"
                properties:
                  username:
                    type: array
                    items:
                      type: string
                      example: "The username field is required."
                  password:
                    type: array
                    items:
                      type: string
                      example: "The password field is required."
              success:
                type: "boolean"
                example: false
              msg:
                type: "string"
                example: "The given data was invalid."
  /user/captcha:
    get:
      tags:
        - "user"
      summary: "Return the Captcha Key and Settings"
      description: "Return the Google Recaptcha Key and the list of actions the captcha is enabled/required for"
      produces:
        - "application/json"
      responses:
        200:
          description: "Captcha Informations"
          schema:
            type: "object"
            properties:
              data:
                type: "object"
                properties:
                  key:
                    type: "string"
                    description: "Pubplic Recaptcha code"
                  login:
                    type: "boolean"
                    description: "Show captcha if the User want to loging"
                    example: true
                  register:
                    type: "boolean"
                    description: "Show captcha if the User want to register"
                    example: true
              success:
                type: "boolean"
                example: true
              msg:
                type: "string"
                example: ""

  /user/invites:
    get:
      tags:
        - "user"
      summary: "Return information about an invite code"
      description: ""
      produces:
        - "application/json"
      parameters:
        - in: query
          name: code
          description: "The invite code"
          required: true
          type: string
      responses:
        200:
          description: "Captcha Informations"
          schema:
            type: "object"
            properties:
              data:
                type: "object"
                properties:
                  usable:
                    type: "boolean"
                    example: true
                    description: "If the value is true the invite code is valide and can be used to register a new account"
                  username:
                    type: "string"
                    description: "If a username is set the user have to use this username for the registration"
                    example: ""
              success:
                type: "boolean"
                example: true
              msg:
                type: "string"
                example: ""
        404:
          description: "Invite code not found"
          schema:
            type: "object"
            properties:
              success:
                type: "boolean"
                example: false
              msg:
                type: "string"
                example: "Resource not Found"
  /user/me:
    get:
      tags:
        - "user"
      summary: "Return information about the current User"
      description: ""
      produces:
        - "application/json"
      responses:
        200:
          description: "Found user and return informations"
          schema:
            type: "object"
            properties:
              data:
                $ref: '#/definitions/User'
              success:
                type: "boolean"
                example: true
              msg:
                type: "string"
                example: ""
        401:
          description: "Not logged in"
          schema:
            type: "object"
            properties:
              success:
                type: "boolean"
                example: false
              msg:
                type: "string"
                example: "You need to login"
  /user/me/mail:
    get:
      tags:
        - "user"
      summary: "Return Mail adddresses for te User"
      description: ""
      produces:
        - "application/json"
      responses:
        200:
          description: "Found user and return informations"
          schema:
            type: "object"
            properties:
              data:
                type: array
                items:
                  $ref: '#/definitions/Mail'
              success:
                type: "boolean"
                example: true
              msg:
                type: "string"
                example: ""
        401:
          description: "Not logged in"
          schema:
            type: "object"
            properties:
              success:
                type: "boolean"
                example: false
              msg:
                type: "string"
                example: "You need to login"
  /account:
    get:
      tags:
        - "account"
        - "admin"
      summary: "ADMIN! Return a list of all users"
      description: "Return a list with all users in the system."
      parameters:
        - in: query
          name: page
          description: "Which page should be returned"
          required: false
          type: string
      responses:
        200:
          description: "Found user and return informations"
          schema:
            type: "object"
            properties:
              data:
                type: array
                items:
                  $ref: '#/definitions/User'
              success:
                type: "boolean"
                example: true
              msg:
                type: "string"
                example: ""
              pagination:
                type: "object"
                properties:
                  currentPage:
                    type: integer
                  pageCount:
                    type: integer
                  itemsPerPage:
                    type: integer
        401:
          description: "Not logged in"
          schema:
            type: "object"
            properties:
              success:
                type: "boolean"
                example: false
              msg:
                type: "string"
                example: "You need to login"
        403:
          description: "You dont have the permission to see this data"
          schema:
            type: "object"
            properties:
              success:
                type: "boolean"
                example: false
              msg:
                type: "string"
                example: "You need to login"
  /account/{id}:
    get:
      tags:
        - "account"
        - "admin"
      summary: "ADMIN! Return a User object"
      description: ""
      parameters:
        - in: path
          name: id
          description: "User ID to get details from"
          required: true
          type: string
      responses:
        200:
          description: "Found user and return informations"
          schema:
            type: "object"
            properties:
              data:
                $ref: '#/definitions/User'
              success:
                type: "boolean"
                example: true
              msg:
                type: "string"
                example: ""
              pagination:
                type: "object"
                properties:
                  currentPage:
                    type: integer
                  pageCount:
                    type: integer
                  itemsPerPage:
                    type: integer
        401:
          description: "Not logged in"
          schema:
            type: "object"
            properties:
              success:
                type: "boolean"
                example: false
              msg:
                type: "string"
                example: "You need to login"
        403:
          description: "You dont have the permission to see this data"
          schema:
            type: "object"
            properties:
              success:
                type: "boolean"
                example: false
              msg:
                type: "string"
                example: "You need to login"
  /app:
    get:
      tags:
        - "apps"
      summary: "Return a list of the Users Apps"
      description: ""
      responses:
        200:
          description: "List of Apps"
          schema:
            type: "object"
            properties:
              data:
                type: array
                items:
                  $ref: '#/definitions/AppForOwner'
              success:
                type: "boolean"
                example: true
              msg:
                type: "string"
                example: ""
              pagination:
                type: "object"
                properties:
                  currentPage:
                    type: integer
                  pageCount:
                    type: integer
                  itemsPerPage:
                    type: integer
    post:
      tags:
        - "apps"
      summary: "Create a new APP"
      description: ""
      produces:
        - "application/json"
      consumes:
        - "multipart/form-data"
        - "application/json"
      parameters:
        - in: formData
          name: name
          description: "Name of the app"
          required: true
          type: string
        - in: formData
          name: description
          description: "Description of the App"
          required: true
          type: string
        - in: formData
          name: url
          description: "App Webpage URL"
          required: true
          type: string
      responses:
        200:
          description: "List of Apps"
          schema:
            type: "object"
            properties:
              data:
                $ref: '#/definitions/AppForOwner'
              success:
                type: "boolean"
                example: true
              msg:
                type: "string"
                example: ""
  /app/find:
    get:
      tags:
        - "apps"
      summary: "Find Apps on the given Informations"
      description: "If no paramtes are given it will return a complete list of all Apps"
      parameters:
        - in: query
          name: apiKey
          description: "Search an app based on the API-Key"
          required: false
          type: string
        - in: query
          name: webpage
          description: "Return Apps shown on the Startpage"
          required: false
          type: boolean
      responses:
        200:
          description: "List of Apps"
          schema:
            type: "object"
            properties:
              data:
                type: array
                items:
                  $ref: '#/definitions/App'
              success:
                type: "boolean"
                example: true
              msg:
                type: "string"
                example: ""
              pagination:
                type: "object"
                properties:
                  currentPage:
                    type: integer
                  pageCount:
                    type: integer
                  itemsPerPage:
                    type: integer
  /app/{id}:
    get:
      tags:
        - "apps"
      summary: "Return information about an app"
      description: "If the User is owner of the App it will return a AppForOwner Object, if not just an App bject."
      parameters:
        - in: path
          name: id
          description: "App ID"
          required: true
          type: string
      responses:
        200:
          description: "List of Apps"
          schema:
            type: "object"
            properties:
              data:
                $ref: '#/definitions/App'
              success:
                type: "boolean"
                example: true
              msg:
                type: "string"
                example: ""
    put:
      tags:
        - "apps"
      summary: "Update App Details"
      description: ""
      produces:
        - "application/json"
      consumes:
        - "multipart/form-data"
        - "application/json"
      parameters:
        - in: path
          name: id
          required: true
          type: integer
        - in: formData
          name: name
          description: "Name of the app"
          required: false
          type: string
        - in: formData
          name: description
          description: "Description of the App"
          required: false
          type: string
        - in: formData
          name: url
          description: "App Webpage URL"
          required: false
          type: string
        - in: formData
          name: direct_url
          description: "Direct Login URL"
          required: false
          type: string
      responses:
        200:
          description: "List of Apps"
          schema:
            type: "object"
            properties:
              data:
                $ref: '#/definitions/AppForOwner'
              success:
                type: "boolean"
                example: true
              msg:
                type: "string"
                example: ""
  /app/{id}/access:
    get:
      tags:
        - "apps"
        - "oAuth"
      summary: "Return Access Information about the current user and this App"
      description: "If the App is auto_accept it will direct creat and return a access object with allowd status. If status is allowed you can redirect the user back to the app."
      produces:
        - "application/json"
      consumes:
        - "multipart/form-data"
        - "application/json"
      parameters:
        - in: path
          name: id
          description: "App ID"
          required: true
          type: string
      responses:
        200:
          description: "List of Apps"
          schema:
            type: "object"
            properties:
              data:
                $ref: '#/definitions/AppAccess'
              success:
                type: "boolean"
                example: true
              msg:
                type: "string"
                example: ""
  /app/{id}/access/allow:
    post:
      tags:
        - "apps"
        - "oAuth"
      summary: "Set the Access to allow and return an appCode/redirectURL"
      description: "If the user clicks on the 'Login to XY' button this endpoint create the code for the App and a return url, the gui redirect the User to this url to finish the login"
      produces:
        - "application/json"
      consumes:
        - "multipart/form-data"
        - "application/json"
      parameters:
        - in: path
          name: id
          description: "App ID"
          required: true
          type: string
        - in: formData
          name: redirect_uri
          description: "The Redirect URL given by the App as GET-Paremter"
          required: true
          type: string
        - in: formData
          name: state
          description: "Give from the APP as GET-Parameter"
          required: false
          type: string
      responses:
        200:
          description: "List of Apps"
          schema:
            type: "object"
            properties:
              data:
                type: "object"
                properties:
                  appCode:
                    type: string
                    description: "Code for the App to create a oAuth Bear and oAuth Refresh token with"
                  redirectUrl:
                    type: string
                    description: "URL to redirect the user to, contains all needet informations."
              success:
                type: "boolean"
                example: true
              msg:
                type: "string"
                example: ""
  /oauth/authorize:
    get:
      tags:
        - "oAuth"
      summary: "Entry Point for Apps to start oAuth workflow"
      consumes:
        - "multipart/form-data"
        - "application/json"
      parameters:
        - in: query
          name: client_id
          description: "API-Key for the App the login should be started"
          required: true
          type: string
        - in: query
          name: redirect_uri
          description: "URL to redirect the user back if he want to join the app"
          required: true
          type: string
        - in: query
          name: state
          description: "Param from the App, added to the redirect url"
          required: false
          type: string
      responses:
        200:
          description: Return a HTML view or redirect the user to a HTML-View to give Access to the App
  /oauth/token:
    post:
      tags:
        - "oAuth"
      summary: "Get Beare Access Token and Refresh Token from AppCode"
      consumes:
        - "multipart/form-data"
        - "application/json"
      parameters:
        - in: formData
          name: code
          description: "Code give from the GET-Request the user is redirectet to."
          required: true
          type: string
      responses:
        200:
          description: Token is valide, the user has logged in
          schema:
            type: object
            properties:
              access_token:
                type: string
                description: Access Token (bearer)
              token_type:
                type: string
                example: "bearer"
              expires_in:
                type: integer
                example: 3600
                description: How long until the tolen expired
              refresh_token:
                type: string
                description: "Refresh tolen to create a new Access Token"
  /server/settings:
    get:
      tags:
        - "server"
      summary: "Get the Server-Settings"
      parameters:
        - in: query
          name: all
          description: "Admin! Return all Settings"
          required: false
          type: boolean
      responses:
        200:
          description: Token is valide, the user has logged in
          schema:
            type: object
            properties:
              data:
                type: "array"
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: Name of the Setting
                    description:
                      type: string
                      description: "Description what the setting is doing"
                    typ:
                      type: string
                      description: "What kind of setting is it"
                      enum:
                        - checkbox
                        - textinput
                        - password
                    value:
                      type: string
                      description: "Value, type based on the typ of the setting"
              success:
                type: "boolean"
                example: true
              msg:
                type: "string"
                example: ""



definitions:
  User:
    type: "object"
    properties:
      id:
        type: "integer"
        format: "int64"
        example: 18
      username:
        type: "string"
        example: "testaccount"
      created_at:
        type: "string"
        format: "DateTime"
        example: "2019-07-17T13:37:40.000000Z"
      updated_at:
        type: "string"
        format: "DateTime"
        example: "2019-07-17T13:37:40.000000Z"
      primaryMail:
        type: "string"
        format: "mail"
        example: "mail@example.com"
      status:
        type: "string"
        description: "Account Status"
        example: "active"
        enum:
          - "active"
      inviteCode:
        type: "string"
        example: "sdjfios"
        description: "Invite Code used to register this Account"
      developer:
        type: "boolean"
        example: false
        description: "If the user is a developer Account (Can create new Apps)"
      admin:
        type: "boolean"
        example: false
        description: "If the user is a admin Account"
  Mail:
    type: "object"
    properties:
      id:
        type: "integer"
        format: "int64"
        example: 18
      created_at:
        type: "string"
        format: "DateTime"
        example: "2019-07-17T13:37:40.000000Z"
      updated_at:
        type: "string"
        format: "DateTime"
        example: "2019-07-17T13:37:40.000000Z"
      status:
        type: "string"
        enum:
          - "valide"
          - "waiting"
          - "invalide"
      primary:
        type: boolean
        description: "If this mail is the user primary mail"
        example: true
      mail:
        type: string
        format: mail
        example: "mail@example.com"

  AppForOwner:
    type: "object"
    properties:
      id:
        type: integer
        description: "ID of the APP"
        example: 42
      created_at:
        type: string
        description: "Time the App was created"
        example: "2019-04-25T13:54:29.000000Z"
      updated_at:
        type: string
        description: "Last time the App was updated"
        example: "2019-07-17T09:23:13.000000Z"
      name:
        type: string
        description: "Name of the App"
        example: "Gitea"
      description:
        type: string
        description: "Description of the App"
        example: "Self-hostet Git server for our organisation"
      url:
        type: string
        description: "URL of the Webpage of the App"
        example: "https://git.keks.cloud"
      directUrl:
        type: string
        description: "Link to log the user in the App, if the user is alweady give access to the App this link should rederect the user direct to the Dashboard"
        example: "https://git.keks.cloud/user/oauth2/KeksAccount"
      apiKey:
        type: string
        description: "The API-Key for the App"
      apiSecret:
        type: string
        description: "The API-Secret for the App"
      properties:
        type: object
        properties:
          testingWarning:
            type: boolean
            description: "Show a warning at the App-Page that the App is in Testing-Modus"
          autoAccept:
            type: boolean
            description: "User don't have to accept to go to the app, if user is at the oAuth-Accept page he will direct redirect to the app"
          untrustedWarning:
            type: boolean
            description: "Show a warning that the app is untrusted"
          showOnWebpage:
            type: boolean
            description: "Show the App on the Startpage of the Webpage"
          stopAutoRedirect:
            type: boolean
            description: "User alwasy have to click at the oAuth-Accept page to get redirect"
          hideInAppList:
            type: boolean
            description: "User don't see this App in his App list"
          userCantRemoveApp:
            type: boolean
            description: "User can't revoe access to this App in his App list"
      access:
        type: object
        properties:
          oAuth:
            type: boolean
            description: "App can use oAuth to autorize user"
          api:
            type: boolean
            description: "App can make API Calls"
          update_apps:
            type: boolean
            description: "App can make Updates to the users app (if the user is developer)"
          update_profile:
            type: boolean
            description: "App can update the Users Profile"
          update_access:
            type: boolean
            description: "App can revoke users Access to other Apps"
          read_access:
            type: boolean
            description: "App can read users information from the api (Currently unimportend)"
          read_apps:
            type: boolean
            description: "App can get a list of the users apps"
          read_profile:
            type: boolean
            description: "App can read the profile from the user"
  App:
    type: "object"
    properties:
      id:
        type: integer
        description: "ID of the APP"
        example: 42
      name:
        type: string
        description: "Name of the App"
        example: "Gitea"
      description:
        type: string
        description: "Description of the App"
        example: "Self-hostet Git server for our organisation"
      url:
        type: string
        description: "URL of the Webpage of the App"
        example: "https://git.keks.cloud"
      directUrl:
        type: string
        description: "Link to log the user in the App, if the user is alweady give access to the App this link should rederect the user direct to the Dashboard"
        example: "https://git.keks.cloud/user/oauth2/KeksAccount"
      properties:
        type: object
        properties:
          testingWarning:
            type: boolean
            description: "Show a warning at the App-Page that the App is in Testing-Modus"
          autoAccept:
            type: boolean
            description: "User don't have to accept to go to the app, if user is at the oAuth-Accept page he will direct redirect to the app"
          untrustedWarning:
            type: boolean
            description: "Show a warning that the app is untrusted"
          showOnWebpage:
            type: boolean
            description: "Show the App on the Startpage of the Webpage"
          stopAutoRedirect:
            type: boolean
            description: "User alwasy have to click at the oAuth-Accept page to get redirect"
          hideInAppList:
            type: boolean
            description: "User don't see this App in his App list"
          userCantRemoveApp:
            type: boolean
            description: "User can't revoe access to this App in his App list"
      access:
        type: object
        properties:
          oAuth:
            type: boolean
            description: "App can use oAuth to autorize user"
          api:
            type: boolean
            description: "App can make API Calls"
          update_apps:
            type: boolean
            description: "App can make Updates to the users app (if the user is developer)"
          update_profile:
            type: boolean
            description: "App can update the Users Profile"
          update_access:
            type: boolean
            description: "App can revoke users Access to other Apps"
          read_access:
            type: boolean
            description: "App can read users information from the api (Currently unimportend)"
          read_apps:
            type: boolean
            description: "App can get a list of the users apps"
          read_profile:
            type: boolean
            description: "App can read the profile from the user"
  AppAccess:
    type: object
    properties:
      app_id:
        type: integer
        description: ID of the App
      user_id:
        type: integer
        description: ID of the User
      status:
        type: string
        enum:
          - "created"
          - "allowed"
          - "disabled"