swagger: '2.0'
info:
  description: Trust Centre API Specification
  version: 0.1.0
  title: Trust Centre API
  contact:
    name: Trust Centre
    url: 'https://www.trustcentre.co.nz/'
    email: 'contact@percolatorly.com'
  license:
    name: MIT License
    url: 'https://opensource.org/licenses/MIT'
host: 'www.trustcentre.co.nz'
basePath: '/api/v0.1/'
schemes:
  - https
paths:
  '/organisations':
    get:
      tags:
        - organisations
      summary: Returns all organisations
      description: This endpoint allows the client to access a collection of organisations that have been onboarded onto the Trust Centre service.
      operationId: getOrganisations
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/authorizationParam'
        - $ref: '#/parameters/ifNoneMatchParam'
        - name: status
          in: query
          description: The status of the organisation in the Trust Centre
          required: false
          type: string
          enum:
            - Active
            - Revoked
        - name: type
          in: query
          description: The type of organisation
          required: false
          type: string
          enum:
            - API Provider
            - Third Party
        - name: nzbn
          in: query
          description: The NZBN of the organisation
          required: false
          type: string
        - name: search
          in: query
          description: Search string for NZBN or organisation name
          required: false
          type: string
      responses:
        '200':
          description: OK
          headers:
            Etag:
              type: string
              description: A response header that is an identifier for a specific version of a resource
          schema:
            properties: 
              data:
                type: array
                items:
                  $ref: '#/definitions/organisation'
        '304':
          $ref: '#/responses/304Response'
        '401':
          $ref: '#/responses/401ErrorResponse'
        '403':
          $ref: '#/responses/403ErrorResponse'
        '429':
          $ref: '#/responses/429ErrorResponse'
        '500':
          $ref: '#/responses/500ErrorResponse'
  '/organisations/{organisationId}':
    get:
      tags:
        - organisations
      summary: Returns a specific organisation
      description: This endpoint allows the client to access a specific organisation that have been onboarded onto the Trust Centre service.
      operationId: getOrganisation
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/authorizationParam'
        - $ref: '#/parameters/ifNoneMatchParam'
        - $ref: '#/parameters/organisationIdParam'
        - name: status
          in: query
          description: The status of the organisation in the Trust Centre
          required: false
          type: string
          enum:
            - Active
            - Revoked
      responses:
        '200':
          description: OK
          headers:
            Etag:
              type: string
              description: A response header that is an identifier for a specific version of a resource
          schema:
            properties:
              data:
                $ref: '#/definitions/organisation'
        '304':
          $ref: '#/responses/304Response'
        '401':
          $ref: '#/responses/401ErrorResponse'
        '403':
          $ref: '#/responses/403ErrorResponse'
        '429':
          $ref: '#/responses/429ErrorResponse'
        '500':
          $ref: '#/responses/500ErrorResponse'
  '/organisations/{organisationId}/keys':
    get:
      tags:
        - keys
      summary: Returns a JWKS for a specific organisation
      description: This endpoint allows the client to access a JWKS for a specific organisation.
      operationId: getOrganisationKeys
      produces:
        - application/jwk-set+json
      parameters:
        - $ref: '#/parameters/authorizationParam'
        - $ref: '#/parameters/ifNoneMatchParam'
        - $ref: '#/parameters/organisationIdParam'
        - name: status
          in: query
          description: The status of the keys in the Trust Centre
          required: false
          type: string
          enum:
            - Active
            - Revoked
      responses:
        '200':
          description: OK
          headers:
            Etag:
              type: string
              description: A response header that is an identifier for a specific version of a resource
          schema:
            properties: 
              keys:
                type: array
                items:
                  $ref: '#/definitions/key'
        '304':
          $ref: '#/responses/304Response'
        '401':
          $ref: '#/responses/401ErrorResponse'
        '403':
          $ref: '#/responses/403ErrorResponse'
        '429':
          $ref: '#/responses/429ErrorResponse'
        '500':
          $ref: '#/responses/500ErrorResponse'
  '/organisations/{organisationId}/keys/{kid}':
    get:
      tags:
        - keys
      summary: Returns a JWK for a specific organisation
      description: This endpoint allows the client to access a specific JWK for a specific organisation.
      operationId: getOrganisationKey
      produces:
        - application/jwk+json
      parameters:
        - $ref: '#/parameters/authorizationParam'
        - $ref: '#/parameters/ifNoneMatchParam'
        - $ref: '#/parameters/organisationIdParam'
        - $ref: '#/parameters/kidParam'
        - name: status
          in: query
          description: The status of the key in the Trust Centre
          required: false
          type: string
          enum:
            - Active
            - Revoked
      responses:
        '200':
          description: OK
          headers:
            Etag:
              type: string
              description: A response header that is an identifier for a specific version of a resource
          schema:
            $ref: '#/definitions/key'
        '304':
          $ref: '#/responses/304Response'
        '401':
          $ref: '#/responses/401ErrorResponse'
        '403':
          $ref: '#/responses/403ErrorResponse'
        '429':
          $ref: '#/responses/429ErrorResponse'
        '500':
          $ref: '#/responses/500ErrorResponse'
  '/organisations/{organisationId}/keys/{kid}/certificate.pem':
    get:
      tags:
        - keys
      summary: Returns the certificate for a specific JWK for a specific organisation
      description: This endpoint allows the client to access the certificate for a specific JWK for a specific organisation.
      operationId: getOrganisationKeyCertificate
      produces:
        - application/x-pem-file
      parameters:
        - $ref: '#/parameters/authorizationParam'
        - $ref: '#/parameters/ifNoneMatchParam'
        - $ref: '#/parameters/organisationIdParam'
        - $ref: '#/parameters/kidParam'
      responses:
        '200':
          description: OK
        '304':
          $ref: '#/responses/304Response'
        '401':
          $ref: '#/responses/401ErrorResponse'
        '403':
          $ref: '#/responses/403ErrorResponse'
        '429':
          $ref: '#/responses/429ErrorResponse'
        '500':
          $ref: '#/responses/500ErrorResponse'
  '/organisations/{organisationId}/auth-servers':
    get:
      tags:
        - authServers
      summary: Returns all authorisation servers for a specific organisation
      description: This endpoint allows the client to access a collection of authorisation servers for a specific organisation.
      operationId: getOrganisationAuthServers
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/authorizationParam'
        - $ref: '#/parameters/ifNoneMatchParam'
        - $ref: '#/parameters/organisationIdParam'
        - name: status
          in: query
          description: The status of the authorisation servers in the Trust Centre
          required: false
          type: string
          enum:
            - Active
            - Revoked
      responses:
        '200':
          description: OK
          headers:
            Etag:
              type: string
              description: A response header that is an identifier for a specific version of a resource
          schema:
            properties: 
              data:
                type: array
                items:
                  $ref: '#/definitions/authServer'
        '304':
          $ref: '#/responses/304Response'
        '401':
          $ref: '#/responses/401ErrorResponse'
        '403':
          $ref: '#/responses/403ErrorResponse'
        '429':
          $ref: '#/responses/429ErrorResponse'
        '500':
          $ref: '#/responses/500ErrorResponse'
  '/organisations/{organisationId}/auth-servers/{authServerId}':
    get:
      tags:
        - authServers
      summary: Returns a specific authorisation server for a specific organisation
      description: This endpoint allows the client to access a specific authorisation server for a specific organisation.
      operationId: getOrganisationAuthServer
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/authorizationParam'
        - $ref: '#/parameters/ifNoneMatchParam'
        - $ref: '#/parameters/organisationIdParam'
        - $ref: '#/parameters/authServerIdParam'
        - name: status
          in: query
          description: The status of the authorisation server in the Trust Centre
          required: false
          type: string
          enum:
            - Active
            - Revoked
      responses:
        '200':
          description: OK
          headers:
            Etag:
              type: string
              description: A response header that is an identifier for a specific version of a resource
          schema:
            properties:
              data:
                $ref: '#/definitions/authServer'
        '304':
          $ref: '#/responses/304Response'
        '401':
          $ref: '#/responses/401ErrorResponse'
        '403':
          $ref: '#/responses/403ErrorResponse'
        '429':
          $ref: '#/responses/429ErrorResponse'
        '500':
          $ref: '#/responses/500ErrorResponse'
  '/organisations/{organisationId}/users':
    get:
      tags:
        - users
      summary: Returns all users for a specific organisation
      description: This endpoint allows the client to access a collection of users for the organisation bound to their authorisation token.
      operationId: getOrganisationUsers
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/authorizationParam'
        - $ref: '#/parameters/ifNoneMatchParam'
        - $ref: '#/parameters/organisationIdParam'
        - $ref: '#/parameters/userIdParam'
        - name: status
          in: query
          description: The status of the users in the Trust Centre
          required: false
          type: string
          enum:
            - Active
            - Revoked
      responses:
        '200':
          description: OK
          headers:
            Etag:
              type: string
              description: A response header that is an identifier for a specific version of a resource
          schema:
            properties: 
              data:
                type: array
                items:
                  $ref: '#/definitions/user'
        '304':
          $ref: '#/responses/304Response'
        '401':
          $ref: '#/responses/401ErrorResponse'
        '403':
          $ref: '#/responses/403ErrorResponse'
        '429':
          $ref: '#/responses/429ErrorResponse'
        '500':
          $ref: '#/responses/500ErrorResponse'
  '/organisations/{organisationId}/users/{userId}':
    get:
      tags:
        - users
      summary: Returns a specific user for a specific organisation
      description: This endpoint allows the client to access a specific user for a specific organisation bound to their authorisation token.
      operationId: getOrganisationUser
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/authorizationParam'
        - $ref: '#/parameters/ifNoneMatchParam'
        - $ref: '#/parameters/organisationIdParam'
        - $ref: '#/parameters/userIdParam'
        - name: status
          in: query
          description: The status of the user in the Trust Centre
          required: false
          type: string
          enum:
            - Active
            - Revoked
      responses:
        '200':
          description: OK
          headers:
            Etag:
              type: string
              description: A response header that is an identifier for a specific version of a resource
          schema:
            properties:
              data:
                $ref: '#/definitions/user'
        '304':
          $ref: '#/responses/304Response'
        '401':
          $ref: '#/responses/401ErrorResponse'
        '403':
          $ref: '#/responses/403ErrorResponse'
        '429':
          $ref: '#/responses/429ErrorResponse'
        '500':
          $ref: '#/responses/500ErrorResponse'
definitions:
  organisation:
    type: object
    description: The organisation resource
    properties:
      organisationId:
        description: Unique identifier for the organisation
        type: string
        format: uuid
      NZBN:
        description: The NZBN for the organisation
        type: string
        minLength: 1
        maxLength: 15
      type:
        description: The type of organisation
        type: string
        enum:
          - API Provider
          - Third Party
          - Admin
      organisationName:
        description: The common name for the organisation
        type: string
        minLength: 1
        maxLength: 100
      status:
        description: The status of the organisation
        type: string
        enum:
          - Active
          - Revoked
      createdDate:
        description: Date and time the organisation resource was created
        type: string
        format: date-time
      updatedDate:
        description: Date and time the organisation resource was updated
        type: string
        format: date-time
      updatedUserId:
        description: User that updated the organisation
        type: string
        format: uuid
    required:
      - organisationId
      - NZBN
      - type
      - organisationName
      - status
      - createdDate
      - updatedDate
      - updatedUserId
    additionalProperties: false
  key:
    type: object
    description: The key resource
    properties:
      kid:
        description: The kid (key ID) parameter is used to match a specific key as per RFC7517
        type: string
      organisationId:
        description: Unique identifier for the organisation
        type: string
        format: uuid
      environment:
        description: The environment using the key
        type: string
        enum:
          - Development
          - Test
          - Integration
          - Staging
          - Production
      name:
        description: The common name for the key
        type: string
        minLength: 1
        maxLength: 100
      kty:
        description: The kty (key type) parameter identifies the cryptographic algorithm family used with the key, such as RSA or EC as per RFC7517
        type: string
        enum:
          - RSA
      use:
        description: The use (public key use) parameter identifies the intended use of the public key as per RFC7517
        type: string
        enum:
          - sig
      e:
        description: RSA public exponent e
        type: string
        enum:
          - AQAB
      n:
        description: RSA public modulus n
        type: string
      x5u:
        description: The x5u (X.509 URL) parameter is a URI [RFC3986] that refers to a resource for an X.509 public key certificate or certificate chain per RFC5280
        type: string
        format: uri
      x5c:
        description: The x5c (X.509 certificate chain) parameter contains a chain of one or more PKIX certificates per RFC5280
        type: array
        items:
          type: string
      alg:
        description: Signature algorithm for the certificate
        type: string
        enum:
          - RS256
          - RS384
          - RS512
          - PS256
          - PS384
          - PS512
      serialNumber:
        description: Serial number for the certificate
        type: string
      keyLength:
        description: Key length for the certificate
        type: integer
      issuerOrganisation:
        description: Issuer organisation for the certificate
        type: string
      subjectOrganisation:
        description: Subject organisation for the certificate
        type: string
      notBeforeDate:
        description: The not before date for the certificate
        type: string
        format: date-time
      notAfterDate:
        description: The not after date for the certificate
        type: string
        format: date-time
      revokedDate:
        description: Date and time the key was revoked
        type: string
        format: date-time
      status:
        description: The status of the organisation
        type: string
        enum:
          - Active
          - Revoked
      createdDate:
        description: Date and time the key resource was created
        type: string
        format: date-time
      updatedDate:
        description: Date and time the key resource was updated
        type: string
        format: date-time
      updatedUserId:
        description: User that updated the key
        type: string
        format: uuid
    required:
      - kid
      - organisationId
      - environment
      - name
      - kty
      - use
      - e
      - n
      - x5u
      - x5c
      - status
      - createdDate
      - updatedDate
      - updatedUserId
    additionalProperties: false
  authServer:
    type: object
    description: The authorisation server resource
    properties:
      authServerId:
        description: Unique identifier for the authorisation server
        type: string
        format: uuid
      organisationId:
        description: Unique identifier for the organisation
        type: string
        format: uuid
      kid:
        description: Unique identifier for the key which is the SHA256 thumbprint of the JWK as per https://tools.ietf.org/html/rfc7638
        type: string
      environment:
        description: The authorisation server environment
        type: string
        enum:
          - Development
          - Test
          - Integration
          - Staging
          - Production
      name:
        description: The common name for the authorisation server
        type: string
        minLength: 1
        maxLength: 100
      description:
        description: The description for the authorisation server
        type: string
        minLength: 1
        maxLength: 300
      baseURI:
        description: The base URI for the authorisation server
        type: string
        format: uri
      wellKnownURI:
        description: The .wellknown URI for the authorisation server
        type: string
        format: uri
      logoURI:
        description: The logo URI for the authorisation server
        type: string
        format: uri
      portalURI:
        description: The developer portal URI for the authorisation server
        type: string
        format: uri
      status:
        description: The status of the organisation
        type: string
        enum:
          - Active
          - Revoked
      createdDate:
        description: Date and time the key resource was created
        type: string
        format: date-time
      updatedDate:
        description: Date and time the key resource was updated
        type: string
        format: date-time
      updatedUserId:
        description: User that updated the key
        type: string
        format: uuid
    required:
      - authServerId
      - organisationId
      - kid
      - environment
      - name
      - description
      - baseURI
      - wellknownURI
      - logoURI
      - portalURI
      - status
      - createdDate
      - updatedDate
      - updatedUserId
    additionalProperties: false
  user:
    type: object
    description: The organisation resource
    properties:
      userId:
        description: Unique identifier for the user
        type: string
        format: uuid
      organisationId:
        description: Unique identifier for the organisation
        type: string
        format: uuid
      firstName:
        description: The first name for the user
        type: string
        minLength: 1
        maxLength: 100
      lastName:
        description: The last name for the user
        type: string
        minLength: 1
        maxLength: 100
      email:
        description: The email for the user
        type: string
        format: email
      status:
        description: The status of the user
        type: string
        enum:
          - Active
          - Revoked
      createdDate:
        description: Date and time the user resource was created
        type: string
        format: date-time
      updatedDate:
        description: Date and time the user resource was updated
        type: string
        format: date-time
      updatedUserId:
        description: User that updated the user resource
        type: string
        format: uuid
    required:
      - userId
      - organisationId
      - firstName
      - lastName
      - email
      - status
      - createdDate
      - updatedDate
      - updatedUserId
    additionalProperties: false
parameters:
  authorizationParam:
    in: header
    name: Authorization
    type: string
    required: true
    description: An access token in the "Authorization" request header field using the "Bearer" authentication scheme as per https://tools.ietf.org/html/rfc6750
  ifNoneMatchParam:
    in: header
    name: If-None-Match
    type: string
    required: false
    description: A request header that makes the GET request conditional based on Etag value
  organisationIdParam:
    name: organisationId
    in: path
    description: Unique identifier for the organisation
    required: true
    type: string
    format: uuid
  kidParam:
    name: kid
    in: path
    description: Unique identifier for the key which is the SHA256 thumbprint of the JWK as per https://tools.ietf.org/html/rfc7638
    required: true
    type: string
  authServerIdParam:
    name: authServerId
    in: path
    description: Unique identifier for the authorisation server
    required: true
    type: string
    format: uuid
  userIdParam:
    name: userId
    in: path
    description: Unique identifier for the user
    required: true
    type: string
    format: uuid
responses:
  304Response:
    description: Not Modified
    headers:
      Etag:
        type: string
        description: A response header that is an identifier for a specific version of a resource
  401ErrorResponse:
    description: Unauthorized
    schema:
      properties:
        data:
          type: object
          description: Error response structure
          properties:
            status:
              description: HTTP status code for error
              type: integer
              enum:
                - 401
            error:
              description: Description for the error
              type: string
            message:
              description: Message for the error
              type: string
          required:
            - status
            - error
            - message
          additionalProperties: false
  403ErrorResponse:
    description: Forbidden
    schema:
      properties:
        data:
          type: object
          description: Error response structure
          properties:
            status:
              description: HTTP status code for error
              type: integer
              enum:
                - 403
            error:
              description: Description for the error
              type: string
            message:
              description: Message for the error
              type: string
          required:
            - status
            - error
            - message
          additionalProperties: false
  429ErrorResponse:
    description: Too Many Requests
    headers:
      Retry-After:
        type: string
        description: A response header that indicates how long to wait in seconds before making a new request.
    schema:
      properties:
        data:
          type: object
          description: Error response structure
          properties:
            status:
              description: HTTP status code for error
              type: integer
              enum:
                - 429
            error:
              description: Description for the error
              type: string
            message:
              description: Message for the error
              type: string
          required:
            - status
            - error
            - message
          additionalProperties: false
  500ErrorResponse:
    description: Internal Server Error
    schema:
      properties:
        data:
          type: object
          description: Error response structure
          properties:
            status:
              description: HTTP status code for error
              type: integer
              enum:
                - 500
            error:
              description: Description for the error
              type: string
            message:
              description: Message for the error
              type: string
          required:
            - status
            - error
            - message
          additionalProperties: false