openapi: 3.1.0
info:
  title: Afero Cloud Users API
  version: v1
  description: 'The Afero Cloud API is the RESTful control plane for the Afero IoT platform: it lists
    the devices and users on an Afero account, reports real-time device state, executes attribute read/write
    actions against connected devices, and manages the over-the-air (OTA) firmware pipeline — firmware
    types, firmware pool images, binary upload, device-type associations, firmware tags, and firmware
    pushes. All requests are made over TLS to https://api.afero.io and are authenticated with an OAuth
    2.0 bearer access token obtained from the /oauth/token endpoint using the partner OAuth Client ID
    and Client Secret issued in the Afero Profile Editor. This OpenAPI was DERIVED by API Evangelist from
    Afero''s public developer documentation (resource URLs, HTTP methods, request headers, request payload
    model schemas, response model schemas and examples transcribed verbatim from the docs); it is NOT
    a provider-published specification. Afero publishes no machine-readable spec: https://api.afero.io/api-docs
    and https://api.afero.io/v1/openapi.json both answer HTTP 401 (authenticated access required), probed
    2026-08-02.'
  contact:
    name: Afero Developer Documentation
    url: https://afero-docs.readthedocs.io/en/latest/CloudAPIs/
    email: sales@afero.io
  license:
    name: Afero Developer Terms of Service
    url: https://cdn.afero.io/tos/developer/v1/developer.html
  x-apievangelist-derived-from: https://afero-docs.readthedocs.io/en/latest/CloudAPIs/
  x-apievangelist-derived-on: '2026-08-02'
  x-apievangelist-provider-published: false
  x-apievangelist-split-from: openapi/_original/afero-cloud-api-openapi.yml
externalDocs:
  description: Afero Developer Docs
  url: https://afero-docs.readthedocs.io/en/latest/
servers:
- url: https://api.afero.io
  description: Afero Cloud API production base URL
tags:
- name: Users
  description: The authenticated end-user, their account and partner access, and terms of service.
  externalDocs:
    url: https://afero-docs.readthedocs.io/en/latest/API-UserEndpoints/
paths:
  /v1/users/me:
    get:
      operationId: getCurrentUser
      tags:
      - Users
      summary: Get information about a user
      description: 'Returns user-specific information for the authenticated end-user: the accounts the
        user can access and the privileges held on each, the sign-in credential, the partner accounts
        and partner privileges held, and the terms-of-service versions accepted or awaiting acceptance.'
      externalDocs:
        url: https://afero-docs.readthedocs.io/en/latest/API-UserEndpoints/
      responses:
        '200':
          description: The authenticated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
      - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'The OAuth 2.0 access token returned by POST /oauth/token, sent as `Authorization:
        Bearer <access_token>`. Tokens expire (approximately four hours per the Afero docs).'
  schemas:
    AccountAccess:
      type: object
      properties:
        account:
          $ref: '#/components/schemas/Account'
        privileges:
          type: object
          properties:
            canWrite:
              type: boolean
            owner:
              type: boolean
    Account:
      type: object
      properties:
        accountId:
          type: string
        createdTimestamp:
          type: integer
        description:
          type: string
        type:
          type: string
          description: The account type, e.g. `CUSTOMER`.
    Error:
      type: object
      description: The Afero Cloud API error envelope, observed live on api.afero.io (2026-08-02).
      properties:
        timestamp:
          type: integer
          description: Epoch milliseconds the error was produced.
        status:
          type: integer
          description: The HTTP status code.
        error:
          type: string
          description: The short error code, e.g. `unauthorized`.
        error_description:
          type: string
          description: Human readable description of the error.
        service_name:
          type: string
          description: The Afero service that produced the error, e.g. `ClientApi`.
        region:
          type: string
          description: The Afero cloud region, e.g. `us-west-2`.
    TermsOfService:
      type: object
      properties:
        tosType:
          type: string
          description: 'The terms type: `user`, `developer` or `general`.'
        currentVersion:
          type: integer
        userVersion:
          type: integer
        needsAcceptance:
          type: boolean
        url:
          type: string
          format: uri
    PartnerAccess:
      type: object
      properties:
        partner:
          $ref: '#/components/schemas/Partner'
        privileges:
          type: object
          properties:
            inviteUsers:
              type: boolean
            manageDeviceProfiles:
              type: boolean
            owner:
              type: boolean
            viewDeviceInfo:
              type: boolean
    Credential:
      type: object
      properties:
        credentialId:
          type: string
          description: The sign-in credential, e.g. an email address.
        failedAttempts:
          type: integer
        lastUsedTimestamp:
          type: integer
        type:
          type: string
          description: The credential type, e.g. `EMAIL`.
        verified:
          type: boolean
    User:
      type: object
      properties:
        userId:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        credential:
          $ref: '#/components/schemas/Credential'
        accountAccess:
          type: array
          items:
            $ref: '#/components/schemas/AccountAccess'
        partnerAccess:
          type: array
          items:
            $ref: '#/components/schemas/PartnerAccess'
        tos:
          type: array
          items:
            $ref: '#/components/schemas/TermsOfService'
    Partner:
      type: object
      properties:
        partnerId:
          type: string
        name:
          type: string
        clientId:
          type: string
          description: The partner OAuth Client ID.
        clientSecret:
          type: string
          description: The partner OAuth Client Secret.
        createdTimestamp:
          type: integer
  responses:
    Unauthorized:
      description: Full authentication is required to access this resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            timestamp: 1785679681261
            status: 401
            error: unauthorized
            error_description: Full authentication is required to access this resource
            service_name: ClientApi
            region: us-west-2
security:
- bearerAuth: []