api.yaml

openapi: '3.0.3'
info:
  version: '1.0.11'
  title: Netsoc IAM
  description: |
    API for managing and authenticating Netsoc users.

servers:
  - url: https://iam.netsoc.ie/v1
  - url: https://iam.staging.netsoc.ie/v1
  - url: http://localhost:8080/v1

components:
  securitySchemes:
    jwt:
      type: http
      scheme: bearer
      bearerFormat: jwt
      description: Any user JWT (including non-admin and expired)
    jwt_admin:
      type: http
      scheme: bearer
      bearerFormat: jwt
      description: Valid admin JWT
    jwt_verify:
      type: http
      scheme: bearer
      bearerFormat: jwt
      description: Email verification token
    jwt_reset:
      type: http
      scheme: bearer
      bearerFormat: jwt
      description: Password reset token

  parameters:
    UserID:
      name: uid
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/UserID'
      description: User ID
    Username:
      name: username
      in: path
      required: true
      schema:
        type: string
      description: User's username.
      example: root
    UsernameOrSelf:
      name: username
      in: path
      required: true
      schema:
        type: string
      description: |
        User's username. Can be `self` to indicate the currently authenticated user.
      example: root

  responses:
    InternalError:
      description: General server error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFoundError:
      description: User with username does not exist
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: Validation error (e.g. Required field missing)
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
    ConflictError:
      description: User with username / email already exists
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
    AuthError:
      description: Authorization error (e.g. incorret password, invalid token, token expired etc.)
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
    AdminError:
      description: Admin token is required
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'

  schemas:
    Error:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: Message explaining the error


    UserID:
      type: integer
      format: int32
      description: Unique database identifier, not modifiable.
      example: 1

    UserMeta:
      type: object
      required:
        - created
        - updated
      description: Metadata about the user, not modifiable.
      properties:
        created:
          type: string
          format: date-time
          description: Date and time at which the user was created
          example: '2020-09-16T16:05:25.911242339Z'
        updated:
          type: string
          format: date-time
          description: Date and time at which the user was last updated
          example: '2020-09-16T16:05:25.911242339Z'

    User:
      type: object
      required:
        - id
        - email
        - username
        - first_name
        - last_name
      properties:
        id:
          $ref: '#/components/schemas/UserID'

        username:
          type: string
          description: Unique username (must be a valid DNS name)
          example: brodude
        email:
          type: string
          pattern: ^\S+@tcd\.ie$
          description: Unique email address (must be `@tcd.ie`)
          example: brodude@tcd.ie
        password:
          type: string
          nullable: true
          minLength: 8
          description: |
            Stored internally as a bcrypt hash. If unset, login will be disabled.
          example: hunter22
        first_name:
          type: string
          example: Bro
        last_name:
          type: string
          example: Dude
        ssh_key:
          type: string
          nullable: true
          description: SSH public key
          example: |
            ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC+kCHXqtznkT9IBN5WxZHmXI97k3BumT+N4lyHWMo0pykpACCOcGw52EXxQveNqgcwcRUgamL9A2JTE//WRf3O4nBofeTRNKcRxTjRoUVIt/F0xbf09yWBqJOXZ8rqLkXhRvSpr1TCUZtYVp5iLtpERp622OMIqHSwa6HlxBqsCFkBeq1bRyNtYK/IaQAuBPW9MNeFriGqA0Vq078ccXp+JINxJbr+ZJybVg6PVqnMD+PgGMZQLkoWjwjH3vcJZZt584UPtrXKpNZuKy6dcMCb2U+O9NOaO66168sBVuK0kZHh51nJ7ZH38VLGiBipRgIQ1fzic3Ncn6GC9ko3/OwT

        verified:
          type: boolean
          nullable: true
          default: false
          description: Indicates if the user's email address is verified. Only modifiable directly by an admin.
        is_admin:
          type: boolean
          nullable: true
          default: false
          description: Indicates if the user is an admin. Only modifiable by an admin.
        renewed:
          type: string
          format: date-time
          description: |
            Date and time when the user's membership was last renewed. Only modifiable by an admin.
          default: '0001-01-01T00:00:00Z'

        meta:
          $ref: '#/components/schemas/UserMeta'

    LoginRequest:
      type: object
      required:
        - password
      properties:
        password:
          type: string
          example: hunter22
    ResetPasswordRequest:
      type: object
      properties:
        password:
          type: string
          example: hunter22
    IssueTokenRequest:
      type: object
      properties:
        duration:
          type: string
          description: |
            Duration of validity for token. Follows [Go's `time.Duration` format](https://pkg.go.dev/time#ParseDuration)
          example: '876000h'

    TokenResponse:
      type: object
      properties:
        token:
          type: string
          example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MzE4MjAxNDcuNjk1OTI0LCJpYXQiOjE2MDAyODc1MTkuODQ4ODk1LCJpc3MiOiJpYW1kIiwibmJmIjoxNjAwMjg3NTE5Ljg0ODg5Nywic3ViIjoiOTAiLCJpc19hZG1pbiI6dHJ1ZSwidmVyc2lvbiI6MX0.M-omIcb7XI9o44_ts6klxFIhNyf4d8kmztMpUxvdKXQ'

paths:
  /users:
    get:
      summary: List users
      operationId: getUsers
      tags: [users]
      security:
        - jwt_admin: []
      responses:
        '200':
          description: An array of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/AuthError'
        '403':
          $ref: '#/components/responses/AdminError'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      summary: Create a new user
      operationId: createUser
      tags: [users]
      security:
        - {}
        - jwt_admin: []
      description: |
        A verification email will automatically be sent to the user's email address.
        Normally this just contains the raw JWT - setting `Accept` to contain `text/html` will send an
        email with a link to the configured UI service and the token.
      requestBody:
        required: true
        description: User to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
            examples:
              registration:
                summary: User self-registration
                value:
                  username: bro
                  email: bro@tcd.ie
                  password: hunter22
                  first_name: Bro
                  last_name: Dude
              admin:
                summary: Admin user
                value:
                  username: admin
                  email: admin@tcd.ie
                  password: hunter22
                  first_name: Admin
                  last_name: Dude
                  is_admin: true
      responses:
        '201':
          description: New user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/AuthError'
        '403':
          $ref: '#/components/responses/AdminError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalError'
  /users/id:{uid}:
    get:
      summary: Get a user by their ID
      operationId: getUserByID
      tags: [users]
      parameters:
        - $ref: '#/components/parameters/UserID'
      security:
        - jwt_admin: []
      description: |
        Requires a valid admin JWT.
      responses:
        '200':
          description: Requested user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/AuthError'
        '403':
          $ref: '#/components/responses/AdminError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalError'
  /users/{username}:
    get:
      summary: Get a user by their username
      operationId: getUser
      tags: [users]
      parameters:
        - $ref: '#/components/parameters/UsernameOrSelf'
      security:
        - jwt: []
        - jwt_admin: []
      description: |
        Requires at least an expired user JWT. A valid admin JWT is required to retrieve a user other than `self`.
      responses:
        '200':
          description: Requested user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/AuthError'
        '403':
          $ref: '#/components/responses/AdminError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      summary: Delete a user by their username
      operationId: deleteUser
      tags: [users]
      parameters:
        - $ref: '#/components/parameters/UsernameOrSelf'
      security:
        - jwt: []
        - jwt_admin: []
      description: |
        Requires at least an expired user JWT. A valid admin JWT is required to delete a user other than `self`.
      responses:
        '200':
          description: Deleted user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/AuthError'
        '403':
          $ref: '#/components/responses/AdminError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalError'
    patch:
      summary: Update a user by their username
      operationId: updateUser
      tags: [users]
      parameters:
        - $ref: '#/components/parameters/UsernameOrSelf'
      security:
        - jwt: []
        - jwt_admin: []
      description: |
        Requires at least an expired user JWT. A valid admin JWT is required to update admin-only
        fields and modify a user other than `self`.

        A verification email will automatically be sent to the user's email address if it has been changed.
        Normally this just contains the raw JWT - setting `Accept` to contain `text/html` will send an
        email with a link to the configured UI service and the token.
      requestBody:
        required: true
        description: Partial user containing fields to update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
            examples:
              profile:
                summary: User self-profile update
                value:
                  last_name: ExtraDude
                  password: password
              admin:
                summary: Admin-only
                value:
                  verified: true
                  renewed: '2100-01-01T00:00:00Z'
                  is_admin: true
      responses:
        '200':
          description: User with un-updated values
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/AuthError'
        '403':
          $ref: '#/components/responses/AdminError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalError'
  /users/{username}/login:
    post:
      summary: Log into a user account (obtain JWT)
      operationId: login
      tags: [users]
      parameters:
        - $ref: '#/components/parameters/Username'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Login token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '401':
          $ref: '#/components/responses/AuthError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      summary: |
        Log out of a user account (invalidate existing JWT's)
      operationId: logout
      tags: [users]
      parameters:
        - $ref: '#/components/parameters/UsernameOrSelf'
      security:
        - jwt: []
        - jwt_admin: []
      description: |
        Requires at least an expired user JWT. A valid admin JWT is required to logout a user
        other than `self`.
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/AuthError'
        '403':
          $ref: '#/components/responses/AdminError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalError'
    patch:
      summary: Verify email address
      operationId: verify
      tags: [users]
      parameters:
        - $ref: '#/components/parameters/UsernameOrSelf'
      security:
        - jwt_verify: []
        - {}
      description: |
        Making a request without a token will generate a token and send it to the user's email address.
        Normally this just contains the raw JWT - setting `Accept` to contain `text/html` will send an
        email with a link to the configured UI service and the token. Passing the returned token to this
        endpoint will perform the verification.
      responses:
        '204':
          description: No content
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/AuthError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      summary: Reset password
      operationId: resetPassword
      tags: [users]
      parameters:
        - $ref: '#/components/parameters/UsernameOrSelf'
      security:
        - jwt_reset: []
        - {}
      description: |
        Making a request without a token (or request body) will generate a token and send it to the
        user's email address.
        Normally this just contains the raw JWT - setting `Accept` to contain `text/html` will send an
        email with a link to the configured UI service and the token. Passing the returned token to this
        endpoint (along with the new password) will perform the reset.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetPasswordRequest'
      responses:
        '204':
          description: No content
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/AuthError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalError'
  /users/self/token:
    get:
      summary: Validate a token
      operationId: validateToken
      tags: [users]
      security:
        - jwt: []
        - jwt_admin: []
      responses:
        '204':
          description: Token is valid
        '401':
          $ref: '#/components/responses/AuthError'
        '500':
          $ref: '#/components/responses/InternalError'
  /users/{username}/token:
    post:
      summary: Issue a token
      operationId: issueToken
      tags: [users]
      parameters:
        - $ref: '#/components/parameters/Username'
      security:
        - jwt_admin: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IssueTokenRequest'
            examples:
              infinity:
                summary: Near-infinite duration
                value:
                  duration: '876000h'
              short:
                summary: (Very) short duration
                value:
                  duration: '30s'
      responses:
        '200':
          description: Issued token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/AuthError'
        '403':
          $ref: '#/components/responses/AdminError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalError'