Afero Cloud Users API

openapi: 3.2.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.'
  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
servers:
- url: https://api.afero.io
  description: Afero Cloud API production base URL
security:
- bearerAuth: []
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:
  schemas:
    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
    Account:
      type: object
      properties:
        accountId:
          type: string
        createdTimestamp:
          type: integer
        description:
          type: string
        type:
          type: string
          description: The account type, e.g. `CUSTOMER`.
    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'
    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`.
    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
    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
    AccountAccess:
      type: object
      properties:
        account:
          $ref: '#/components/schemas/Account'
        privileges:
          type: object
          properties:
            canWrite:
              type: boolean
            owner:
              type: boolean
    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
  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
  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).'
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic with the partner OAuth Client ID as username and OAuth Client Secret as password, used only on POST /oauth/token.
externalDocs:
  description: Afero Developer Docs
  url: https://afero-docs.readthedocs.io/en/latest/