swagger.yaml

basePath: /api
definitions:
  AuthUpdateMessage:
    description: Message that is sent to notify subscribers (e.g. Beacon) on changes
      to one of these authentication related values
    properties:
      api_token:
        description: the actual API token
        type: string
      expires_at:
        description: expiration date of this token
        type: string
      permanent:
        description: no expiration (ignore ExpiresAt)
        type: boolean
      roles:
        description: roles associated with this token
        items:
          type: string
        type: array
      username:
        description: unique username associated with this token
        type: string
    type: object
  CreateOrUpdateRolePayload:
    properties:
      name:
        type: string
    type: object
  CreateOrUpdateUserPayload:
    properties:
      email:
        type: string
      password:
        type: string
      username:
        type: string
    type: object
  CreateRegistrationKeyPayload:
    properties:
      description:
        type: string
      expires_at:
        type: string
      key:
        type: string
      permanent:
        type: boolean
    type: object
  LoginPayload:
    properties:
      password:
        type: string
      username:
        type: string
    type: object
  RegisterPayload:
    properties:
      email:
        type: string
      password:
        type: string
      registration_key:
        description: snake case naming for decoding of x-www-form-urlencoded bodies
        type: string
      username:
        type: string
    type: object
  RegistrationKey:
    description: A registration key that can be permanent or expire at a specified
      date and time with which new users can register an account
    properties:
      created_at:
        description: ISO 8601 datetime
        type: string
      description:
        description: a description for this registration key
        type: string
      expires_at:
        description: expiration date in ISO 8601 datetime
        type: string
      id:
        description: id (primary key)
        type: integer
      key:
        description: unique registration key
        type: string
      permanent:
        description: if set, ignores the expires_at field and never expires this key
        type: boolean
      updated_at:
        description: ISO 8601 datetime
        type: string
    type: object
  Role:
    description: A named role that describes a group of users sharing the same permissions
    properties:
      created_at:
        description: ISO 8601 datetime
        type: string
      id:
        description: id (primary key)
        type: integer
      name:
        description: unique name of the role
        type: string
      updated_at:
        description: ISO 8601 datetime
        type: string
    type: object
  Token:
    description: API token that allows access to the websocket API (beacon) and probably
      other APIs in the future
    properties:
      api_token:
        type: string
      created_at:
        description: ISO 8601 datetime
        type: string
      expires_at:
        description: ISO 8601 datetime
        type: string
      permanent:
        description: if permanent is true, expires_at is ignored
        type: boolean
      updated_at:
        description: ISO 8601 datetime
        type: string
    type: object
  UpdateRegistrationKeyPayload:
    properties:
      description:
        type: string
      expires_at:
        type: string
      permanent:
        type: boolean
    type: object
  User:
    description: User account information including username, email, last login date
      and time, permanent API token flag, registration key (if user registered with
      a key) and roles
    properties:
      api_token:
        allOf:
        - $ref: '#/definitions/Token'
        description: omitted if null (user doesn't have an API token)
      created_at:
        description: ISO 8601 datetime
        type: string
      email:
        description: can be empty
        type: string
      id:
        description: id (primary key)
        type: integer
      last_login:
        description: ISO 8601 datetime
        type: string
      registration_key:
        allOf:
        - $ref: '#/definitions/RegistrationKey'
        description: omitted if null (when user was created and not registered or
          when list of users is queried to not leak other users keys)
      roles:
        items:
          $ref: '#/definitions/Role'
        type: array
      updated_at:
        description: ISO 8601 datetime
        type: string
      username:
        description: must be unique
        type: string
    type: object
  UserUpdateMessage:
    description: Message that is sent to notify subscribers (e.g. Beacon) when a new
      user is created or a user is removed
    properties:
      removed:
        type: boolean
      username:
        type: string
    type: object
  handler.UpdateTokenPayload:
    properties:
      permanent:
        type: boolean
    type: object
host: https://lighthouse.uni-kiel.de
info:
  contact: {}
  description: |-
    This is the REST API of Project Lighthouse that manages users, roles, registration keys, API tokens and everything about authentication and authorization.
    NOTE: This API is an early alpha version that still needs a lot of testing (unit tests, end-to-end tests and security tests)
  title: Heimdall Lighthouse API
  version: "0.1"
paths:
  /internal/authenticate/{username}:
    post:
      description: If the initial request was successful, the connection is kept alive
        and updates are sent using server sent events (SSE).
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/AuthUpdateMessage'
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "500":
          description: Internal Server Error
      summary: Get and subscribe to updates of a user's api token and roles
      tags:
      - Internal
  /internal/users:
    get:
      description: Returns a list of all users names
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              $ref: '#/definitions/UserUpdateMessage'
            type: array
        "401":
          description: Unauthorized
        "500":
          description: Internal Server Error
      summary: Get a list of all usernames
      tags:
      - Internal
  /login:
    post:
      consumes:
      - application/json
      description: Log in with username and password (sets a cookie with the session
        id). Returns the full user information if the login was successful or the
        user is already logged in.
      parameters:
      - description: Username and Password
        in: body
        name: payload
        required: true
        schema:
          $ref: '#/definitions/LoginPayload'
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/User'
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "500":
          description: Internal Server Error
      summary: Login
      tags:
      - Users
  /logout:
    post:
      consumes:
      - application/json
      description: Log out of the current session
      produces:
      - text/plain
      responses:
        "200":
          description: OK
        "401":
          description: Unauthorized
        "500":
          description: Internal Server Error
      summary: Logout
      tags:
      - Users
  /register:
    post:
      consumes:
      - application/json
      description: Registers a new user using a registration key
      parameters:
      - description: Username, Password, Email, RegistrationKey
        in: body
        name: payload
        required: true
        schema:
          $ref: '#/definitions/RegisterPayload'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            $ref: '#/definitions/User'
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "409":
          description: Conflict
        "500":
          description: Internal Server Error
      summary: Register user
      tags:
      - Users
  /registration-keys:
    get:
      consumes:
      - application/json
      description: Get a list of all registration keys or query a single registration
        key by key (returns single object instead of list)
      parameters:
      - description: Registration Key
        in: query
        name: key
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              $ref: '#/definitions/RegistrationKey'
            type: array
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
      summary: Get all registration keys or query by key
      tags:
      - RegistrationKeys
    post:
      consumes:
      - application/json
      description: Create a new registration key
      parameters:
      - description: key, description, permament, expires_at
        in: body
        name: payload
        required: true
        schema:
          $ref: '#/definitions/CreateRegistrationKeyPayload'
      produces:
      - text/plain
      responses:
        "201":
          description: Created
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "409":
          description: Conflict
        "500":
          description: Internal Server Error
      summary: Create registration key
      tags:
      - RegistrationKeys
  /registration-keys/{id}:
    delete:
      description: Delete a registration key by its id
      parameters:
      - description: Registration Key ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - text/plain
      responses:
        "200":
          description: OK
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
      summary: Delete registration key
      tags:
      - RegistrationKeys
    get:
      consumes:
      - application/json
      description: Get a registration key by its id
      parameters:
      - description: Registration Key ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/RegistrationKey'
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
      summary: Get registration key by id
      tags:
      - RegistrationKeys
    put:
      consumes:
      - application/json
      description: Upadte a registration key by its id
      parameters:
      - description: Registration Key ID
        in: path
        name: id
        required: true
        type: integer
      - description: description, permament, expires_at
        in: body
        name: payload
        required: true
        schema:
          $ref: '#/definitions/UpdateRegistrationKeyPayload'
      produces:
      - text/plain
      responses:
        "200":
          description: OK
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "500":
          description: Internal Server Error
      summary: Update registration key
      tags:
      - RegistrationKeys
  /registration-keys/{id}/users:
    get:
      description: 'Get a list of users that registered using this registration key
        by its id. NOTE: registration_key is not included for users'
      parameters:
      - description: Registration Key ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              $ref: '#/definitions/User'
            type: array
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
      summary: Get users of registration key
      tags:
      - RegistrationKeys
  /roles:
    get:
      description: Get a list of all roles or query a single role by name (returns
        single object instead of list)
      parameters:
      - description: Role name
        in: query
        name: name
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/Role'
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
      summary: Get all roles or query by name
      tags:
      - Roles
    post:
      consumes:
      - application/json
      description: Create a new role
      parameters:
      - description: Name
        in: body
        name: payload
        required: true
        schema:
          $ref: '#/definitions/CreateOrUpdateRolePayload'
      produces:
      - text/plain
      responses:
        "201":
          description: Created
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "409":
          description: Conflict
        "500":
          description: Internal Server Error
      summary: Create role
      tags:
      - Roles
  /roles/{id}:
    delete:
      description: Delete a role by its role id
      parameters:
      - description: Role ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - text/plain
      responses:
        "200":
          description: OK
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
      summary: Delete role
      tags:
      - Roles
    get:
      description: Get a role by its role id
      parameters:
      - description: Role ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/Role'
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
      summary: Get role by id
      tags:
      - Roles
    put:
      consumes:
      - application/json
      description: Update a new role by its user id
      parameters:
      - description: Role ID
        in: path
        name: id
        required: true
        type: integer
      - description: Name
        in: body
        name: payload
        required: true
        schema:
          $ref: '#/definitions/CreateOrUpdateRolePayload'
      produces:
      - text/plain
      responses:
        "200":
          description: OK
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "409":
          description: Conflict
        "500":
          description: Internal Server Error
      summary: Update role
      tags:
      - Roles
  /roles/{id}/users:
    get:
      description: 'Get a list of users that have a role by its role id. NOTE: registration_key
        is not included for users'
      parameters:
      - description: Role ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              $ref: '#/definitions/User'
            type: array
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
      summary: Get users of role
      tags:
      - Roles
  /roles/{roleid}/users/{userid}:
    delete:
      description: Remove a user (by its user id) from a role (by its role id)
      parameters:
      - description: Role ID
        in: path
        name: roleid
        required: true
        type: integer
      - description: User ID
        in: path
        name: userid
        required: true
        type: integer
      produces:
      - text/plain
      responses:
        "200":
          description: OK
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
      summary: Remove user from role
      tags:
      - Roles
    put:
      description: Add a user (by its user id) to a role (by its role id)
      parameters:
      - description: Role ID
        in: path
        name: roleid
        required: true
        type: integer
      - description: User ID
        in: path
        name: userid
        required: true
        type: integer
      produces:
      - text/plain
      responses:
        "200":
          description: OK
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
      summary: Add user to role
      tags:
      - Roles
  /users:
    get:
      description: 'Get a list of all users or query a single user by name (returns
        single object instead of list). NOTE: registration_key is only included when
        querying a single user'
      parameters:
      - description: Username
        in: query
        name: name
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              $ref: '#/definitions/User'
            type: array
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
      summary: Get all users or query by name
      tags:
      - Users
    post:
      consumes:
      - application/json
      description: Creates a new user
      parameters:
      - description: Username, Password, Email
        in: body
        name: payload
        required: true
        schema:
          $ref: '#/definitions/CreateOrUpdateUserPayload'
      produces:
      - text/plain
      responses:
        "201":
          description: Created
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "409":
          description: Conflict
        "500":
          description: Internal Server Error
      summary: Create user
      tags:
      - Users
  /users/{id}:
    delete:
      description: Deletes a user given a user id
      parameters:
      - description: User ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - text/plain
      responses:
        "200":
          description: OK
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
      summary: Delete user
      tags:
      - Users
    get:
      description: Get a user by its user id
      operationId: GetUserByName
      parameters:
      - description: User ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/User'
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
      summary: Get user by id
      tags:
      - Users
    put:
      consumes:
      - application/json
      description: Updates a user (always updates all fields, partial updates currently
        not supported)
      parameters:
      - description: User ID
        in: path
        name: id
        required: true
        type: integer
      - description: Username, Password, Email
        in: body
        name: payload
        required: true
        schema:
          $ref: '#/definitions/CreateOrUpdateUserPayload'
      produces:
      - text/plain
      responses:
        "200":
          description: OK
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
        "409":
          description: Conflict
        "500":
          description: Internal Server Error
      summary: Update user
      tags:
      - Users
  /users/{id}/api-token:
    delete:
      description: Given a valid user id, invalidates the current API token and generates
        a new one
      parameters:
      - description: User ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - text/plain
      responses:
        "200":
          description: OK
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
      summary: Renew a user's API token
      tags:
      - Users
    get:
      description: Given a valid user id, returns the username, API token, associated
        roles and expiration date
      parameters:
      - description: User ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/Token'
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
      summary: Get a user's API token
      tags:
      - Users
    put:
      description: Given a valid user id and new permanent status, sets the permanent
        status for the users current token
      parameters:
      - description: User ID
        in: path
        name: id
        required: true
        type: integer
      - description: Set whether this token is permanent (does not expire)
        in: body
        name: payload
        required: true
        schema:
          $ref: '#/definitions/handler.UpdateTokenPayload'
      produces:
      - application/json
      responses:
        "200":
          description: OK
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
      summary: Update a user's API token (set permanent)
      tags:
      - Users
  /users/{id}/roles:
    get:
      description: Get a list of roles that a user posesses
      parameters:
      - description: User ID
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              $ref: '#/definitions/Role'
            type: array
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
      summary: Get roles of user
      tags:
      - Users
swagger: "2.0"