openapi: 3.0.0
info:
  title: nRF Cloud
  description: >-
    API definition for the <a href="https://nrfcloud.com" target="_blank"
    rel="noopener noreferrer">nRF Cloud</a> REST API.<br> <strong>Note:</strong>
    This is a preview release and might be changed without notice.<br>
    <strong>Warning:</strong> Do not hardcode the endpoint listed below, but
    find the endpoint for your desired stage using a call to <a
    href="https://github.com/nRFCloud/meta" target="_blank" rel="noopener
    noreferrer">meta.nrfcloud.com</a>.
  contact:
    name: nRF Cloud
    url: 'https://nrfcloud.com/'
    email: admin@nrfcloud.com
  license:
    name: MIT License
    url: 'https://opensource.org/licenses/MIT'
  version: 1.0.0-preview.1
servers:
  - description: >-
      The API endpoint to use.<br> Do not hardcode this, but find the endpoint
      for your desired stage using a call to
      <code>https://meta.nrfcloud.com/</code>.
    url: 'https://hnmr2uba55.execute-api.us-east-1.amazonaws.com/dev'
components:
  securitySchemes:
    Token:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    ApiIndex:
      title: ApiIndex
      description: Describes entry points of an API.
      type: object
      allOf:
        - $ref: '#/components/schemas/VersionedContext'
        - properties:
            links:
              type: array
              description: Links to entry points
              items:
                $ref: '#/components/schemas/Link'
          additionalProperties: false
          required:
            - links
    GatewayRegistrationResult:
      title: GatewayRegistrationResult
      description: Contains the credentials for the created Gateway
      type: object
      properties:
        gatewayId:
          type: string
        clientCert:
          type: string
        privateKey:
          type: string
      additionalProperties: false
      required:
        - gatewayId
        - clientCert
        - privateKey
    HttpProblem:
      title: HttpProblem
      description: 'See https://datatracker.ietf.org/doc/draft-ietf-appsawg-http-problem/'
      type: object
      allOf:
        - $ref: '#/components/schemas/VersionedContext'
        - properties:
            type:
              type: string
              description: >-
                A URI reference [RFC3986] that identifies the problem type. When
                dereferenced, it is encouraged to provide human-readable
                documentation for the problem type (e.g., using  HTML
                [W3C.REC-html401-19991224]).
              pattern: >-
                ^https?:\/\/(((?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9][a-z0-9-]{0,61}[a-z0-9])|((?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)))(:(6553[0-5]|655[0-2]\d|65[0-4]\d\d|6[0-4]\d{3}|[1-5]\d{4}|[1-9]\d{0,3}|0))?(\/[-a-zA-Z0-9@:%_+.,~?&/=()]*)*(#(?:[^#^[\]{}\\"<>%\s]|%[0-9a-f]{2})*)*$
            title:
              type: string
              description: 'A short, human-readable summary of the problem type.'
            status:
              type: integer
              description: >-
                The HTTP status code (RFC7231, Section 6) generated by the
                origin server for this occurrence of the problem.
              minimum: 100
              maximum: 599
              format: int32
            detail:
              type: string
              description: >-
                An human readable explanation specific to this occurrence of the
                problem.
          additionalProperties: false
          required:
            - type
            - title
            - status
    Link:
      title: Link
      description: Describes a link.
      type: object
      allOf:
        - $ref: '#/components/schemas/VersionedContext'
        - properties:
            href:
              description: URL to retrieve the link
              example: 'https://meta.nrfcloud.com/'
              type: string
              pattern: >-
                ^https?:\/\/(((?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9][a-z0-9-]{0,61}[a-z0-9])|((?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)))(:(6553[0-5]|655[0-2]\d|65[0-4]\d\d|6[0-4]\d{3}|[1-5]\d{4}|[1-9]\d{0,3}|0))?(\/[-a-zA-Z0-9@:%_+.,~?&/=()]*)*(#(?:[^#^[\]{}\\"<>%\s]|%[0-9a-f]{2})*)*$
            subject:
              description: Context of the linked item
              example: 'https://github.com/nRFCloud/models#ApiIndex'
              type: string
              pattern: >-
                ^https?:\/\/(((?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9][a-z0-9-]{0,61}[a-z0-9])|((?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)))(:(6553[0-5]|655[0-2]\d|65[0-4]\d\d|6[0-4]\d{3}|[1-5]\d{4}|[1-9]\d{0,3}|0))?(\/[-a-zA-Z0-9@:%_+.,~?&/=()]*)*(#(?:[^#^[\]{}\\"<>%\s]|%[0-9a-f]{2})*)*$
            rel:
              description: Label of the relation
              example: self
              type: string
          additionalProperties: false
          required:
            - href
            - subject
    LinkedEntity:
      title: LinkedEntity
      type: object
      allOf:
        - $ref: '#/components/schemas/VersionedContext'
        - type: object
          properties:
            $links:
              type: array
              description: Links between entities
              items:
                $ref: '#/components/schemas/Link'
          additionalProperties: false
          required:
            - $links
    List:
      title: List
      type: object
      description: >-
        Describes a list if items. Can contain links to e.g. fetch the next page
        in a result set.
      allOf:
        - $ref: '#/components/schemas/LinkedEntity'
        - type: object
          properties:
            items:
              type: array
              description: Items in the list
              items:
                $ref: '#/components/schemas/LinkedEntity'
            total:
              type: integer
              minimum: 0
              description: Total number of items for the query
          additionalProperties: false
          required:
            - items
            - total
    Status:
      title: Status
      description: Describes the status of the system.
      type: object
      allOf:
        - $ref: '#/components/schemas/VersionedContext'
        - properties:
            maintenance:
              description: Whether the system is in maintenance mode.
              example: false
              type: boolean
            version:
              description: >-
                The global version of the system. This is merely a logical
                version identifier for the system as whole since individual
                services may have their own version scheme. This is a semantic
                version string: http://semver.org/
              example: 1.0.0-beta.2
              type: string
            time:
              description: Time of the status creation.
              example: '2017-10-02T11:05:46.793Z'
              type: string
              format: date-time
          additionalProperties: false
          required:
            - maintenance
            - version
            - time
    Tenant:
      title: Tenant
      description: A tenant
      type: object
      properties:
        id:
          type: string
          description: Unique identifier representing the tenant.
        name:
          type: string
          description: The name of the tenant
        createdAt:
          type: string
          format: date-time
          description: Timestamp when tenant was created.
        createdBy:
          type: string
          description: The user that created the tenant.
        users:
          type: array
          items:
            type: string
      additionalProperties: false
      required:
        - id
        - name
        - createdAt
        - createdBy
        - users
    TenantsList:
      title: TenantsList
      description: A list of tenants
      type: array
      items:
        $ref: '#/components/schemas/Tenant'
    VersionedContext:
      title: VersionedContext
      description: >-
        All entities require a 'context' which explicitly types their JSON
        representation. The version is used to express schema changes per
        entity.
      type: object
      properties:
        $context:
          description: context for this model
          type: string
          pattern: >-
            ^https?:\/\/(((?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9][a-z0-9-]{0,61}[a-z0-9])|((?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)))(:(6553[0-5]|655[0-2]\d|65[0-4]\d\d|6[0-4]\d{3}|[1-5]\d{4}|[1-9]\d{0,3}|0))?(\/[-a-zA-Z0-9@:%_+.,~?&/=()]*)*(#(?:[^#^[\]{}\\"<>%\s]|%[0-9a-f]{2})*)*$
          example: 'https://github.com/nRFCloud/models#Status'
        $contextVersion:
          description: version of the context
          example: 1
          type: integer
          minimum: 1
          format: int32
      additionalProperties: false
      required:
        - $context
        - $contextVersion
paths:
  /tenants:
    post:
      summary: Fetch user's tenant
      tags:
        - Account
        - Gateway
      description: Returns the tenants for a user (and creating them if they do not exist)
      operationId: listTenants
      responses:
        '200':
          description: The tenants for the authenticated user
          headers: &ref_0
            Access-Control-Allow-Origin:
              description: Allow any origin to access this resource.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantsList'
        '201':
          description: A list with the the tenant which was just created.
          headers: *ref_0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantsList'
        '400':
          description: >-
            The supplied request data was invalid. Check the response body for
            details.
          headers: *ref_0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpProblem'
        '404':
          description: An entity was not found. Check the response body for details.
          headers: *ref_0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpProblem'
        '500':
          description: An internal error occurred. Check the response body for details.
          headers: *ref_0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpProblem'
      parameters:
        - name: create
          description: >-
            Set this parameter to `true` to create a new tenant if no tenant
            exists for the authenticated user
          in: query
          schema:
            type: string
  '/tenants/{tenantId}/gateways':
    post:
      summary: Register new Gateway
      tags:
        - Gateway
      description: Registers a new Gateway and returns the certificate
      operationId: registerGateway
      responses:
        '201':
          description: The certificate for the newly created gateway
          headers: *ref_0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayRegistrationResult'
        '400':
          description: >-
            The supplied request data was invalid. Check the response body for
            details.
          headers: *ref_0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpProblem'
        '403':
          description: Access was denied. Check the response body for details.
          headers: *ref_0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpProblem'
        '500':
          description: An internal error occurred. Check the response body for details.
          headers: *ref_0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpProblem'
      parameters:
        - name: tenantId
          description: Id of the tenant to register the gateway for
          required: true
          in: path
          schema:
            type: string