Afero Cloud Authentication API

openapi: 3.2.0
info:
  title: Afero Cloud Authentication 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: Authentication
  description: OAuth 2.0 token issuance for Afero Cloud API access.
  externalDocs:
    url: https://afero-docs.readthedocs.io/en/latest/API-OAuthEndpoints/
paths:
  /oauth/token:
    post:
      operationId: createAccessToken
      tags:
      - Authentication
      summary: OAuth Authentication
      description: 'Authenticate an end-user and generate an OAuth 2.0 access token used to authenticate subsequent requests on behalf of that end-user. The Authorization header is HTTP Basic: the string `Basic ` followed by the Base64 encoding of `:`. The returned access token expires (the docs note approximately four hours; the `expires_in` value is in seconds).'
      externalDocs:
        url: https://afero-docs.readthedocs.io/en/latest/API-OAuthEndpoints/
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenRequest'
      responses:
        '200':
          description: An OAuth 2.0 access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessToken'
              example:
                access_token: 12345678-90AB-CDEF-0123-FED789CBA432
                token_type: bearer
                expires_in: 16086
                scope: partner account
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
      - basicAuth: []
components:
  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
  schemas:
    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`.
    AccessToken:
      type: object
      properties:
        access_token:
          type: string
          description: The bearer access token.
        token_type:
          type: string
          description: The token type; `bearer`.
        expires_in:
          type: integer
          description: Seconds until the token expires.
        scope:
          type: string
          description: Space-delimited granted scopes, e.g. `partner account`.
    TokenRequest:
      type: object
      required:
      - username
      - password
      - grant_type
      properties:
        username:
          type: string
          description: The end-user's Afero username (email address).
        password:
          type: string
          format: password
          description: The end-user's Afero password.
        grant_type:
          type: string
          enum:
          - password
          description: The OAuth 2.0 grant type.
  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/