openapi: 3.0.3
info:
  title: Arcadia API Reference Auth Utility Credentials API
  version: 0.3.0
  contact:
    email: platformsupport@arcadia.com
servers:
- url: https://api.arcadia.com
security:
- bearerAuth: []
tags:
- name: Utility Credentials
paths:
  /utility_credentials:
    get:
      tags:
      - Utility Credentials
      summary: List Utility Credentials
      description: Returns a paginated list of UtilityCredentials for all users, or filtered by `client_user_id`. Default ordered by descending `updated_at`.
      operationId: getUtilityCredentials
      parameters:
      - $ref: '#/components/parameters/clientUserIdQueryParam'
      - $ref: '#/components/parameters/paginationLimitParam'
      - $ref: '#/components/parameters/paginationUpdatedAfterParam'
      - $ref: '#/components/parameters/paginationUpdatedBeforeParam'
      - $ref: '#/components/parameters/paginationOrderParam'
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      responses:
        '200':
          description: Success
          headers:
            Arcadia-Version:
              $ref: '#/components/headers/ArcVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUtilityCredentials'
  /utility_credentials/{utility_credential_id}:
    get:
      tags:
      - Utility Credentials
      summary: Get Utility Credential
      description: Returns a single UtilityCredential specified by ID.
      operationId: getUtilityCredential
      parameters:
      - $ref: '#/components/parameters/utilityCredentialIdInPathParam'
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      responses:
        '200':
          description: Success
          headers:
            Arcadia-Version:
              $ref: '#/components/headers/ArcVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UtilityCredential'
  /sandbox/connect/submit_test_credentials:
    post:
      tags:
      - Utility Credentials
      summary: Submit test credentials
      description: 'Submit test credentials in the sandbox environment


        The request should authenticate with a Bearer token from the [Connect Token endpoint](ref:createconnecttoken), provisioned in the same manner as it would be for front-end use with Connect.

        '
      operationId: submitTestCredentials
      parameters:
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - username
              - password
              - utility_id
              - zip
              properties:
                username:
                  type: string
                password:
                  type: string
                account_number:
                  type: string
                  description: Alternative to username/password, for use with ConEd
                utility_id:
                  type: string
                  description: Arcadia identifier for the desired utility, found in the [Supported Utilities section](#section/Supported-Utilities).
                zip:
                  type: string
                  description: Zip code of the test utility account service address. This can influence tariffs under some utilities.
      responses:
        '201':
          description: Success
          headers:
            Arcadia-Version:
              $ref: '#/components/headers/ArcVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UtilityCredential'
components:
  headers:
    ArcVersion:
      description: The Arcadia-Version for the response
      schema:
        type: string
      example: '2022-10-13'
      required: true
  parameters:
    arcVersionInHeaderParam:
      name: Arcadia-Version
      in: header
      example: '2022-10-13'
      description: The Arcadia-Version for the request
      required: true
      schema:
        type: string
        default: '2022-10-13'
    paginationUpdatedBeforeParam:
      in: query
      name: updated_before
      required: false
      description: ISO8601 datetime, used to traverse paginated responses. Use of this parameter is mutually exclusive with `updated_after`.
      schema:
        type: string
        format: date-time
    clientUserIdQueryParam:
      in: query
      name: client_user_id
      required: false
      description: A client_user_id to filter the list of returned items by.
      schema:
        type: string
    paginationUpdatedAfterParam:
      in: query
      name: updated_after
      required: false
      description: ISO8601 datetime, used to traverse paginated responses. Use of this parameter is mutually exclusive with `updated_before`.
      schema:
        type: string
        format: date-time
    utilityCredentialIdInPathParam:
      name: utility_credential_id
      in: path
      required: true
      schema:
        type: integer
    paginationLimitParam:
      in: query
      name: limit
      required: false
      schema:
        type: integer
        minimum: 1
        default: 10
    paginationOrderParam:
      in: query
      name: order
      required: false
      description: Used to specify the order in which records should be returned. Currently ordered by `updated_at` timestamp.
      schema:
        type: string
        enum:
        - asc
        - desc
        default: desc
  schemas:
    UtilityCredential:
      required:
      - created_at
      - id
      - updated_at
      - client_user_id
      - username
      - utility_name
      - utility_long_name
      - verification_status
      - accounts_load_in_progress
      - verification_updated_at
      - sandboxed
      - uses_test_scenario
      properties:
        id:
          type: integer
          example: 12345
        client_user_id:
          type: string
          example: fff57dc7-3a2b-4395-8a62-e3486d46dabe
        utility_name:
          type: string
          example: AEP SWEPCO
          description: The list of supported Arcadia utilities can be found [here](https://arc.arcadia.com/coverage?first=25&page=1).
        utility_long_name:
          type: string
          example: AEP SWEPCO AR
          description: Provides greater detail than `utility_name`. The list of supported Arcadia utilities can be found [here](https://arc.arcadia.com/coverage?first=25&page=1).
        username:
          type: string
          example: great_customer
          nullable: true
        verification_status:
          type: string
          enum:
          - pending
          - verified
          - rejected
          - error
          description: 'The verification status of the Utility Credential.


            * `pending`: Credential verification is pending

            * `verified`: The credentials were found to be correct

            * `rejected`: The credentials were found to be incorrect

            * `error`: There was an error attempting to verify the credentials. This status _may_ be transient, as Arcadia will continue to retry verification in the background.

            '
        accounts_load_in_progress:
          type: boolean
          example: false
          description: 'Indicates if Arcadia is in the process of verifying a utility credential or loading associated utility accounts. The combination of `verification_status: verified` and `account_load_in_progress: false` will indicate that utility accounts are available in the API. Alternatively, the `utility_accounts_discovered` webhook will alert you when utility accounts are available in the API.'
        verification_updated_at:
          format: date-time
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        sandboxed:
          type: boolean
          example: false
        uses_test_scenario:
          type: boolean
          example: false
          description: Indicates if the utility credential was created using a designated test username and password.
    PaginatedUtilityCredentials:
      required:
      - data
      - total_count
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/UtilityCredential'
        total_count:
          type: integer
          example: 1
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
x-readme:
  proxy-enabled: false
  headers:
  - key: from-readme
    value: true
x-tagGroups:
- name: General
  tags:
  - Auth
  - Webhooks
  - Webhook Events
- name: Connections
  tags:
  - Utility Credentials
  - Utility Accounts
  - Utility Meters (Beta)
  - Users
- name: Products
  tags:
  - Plug
  - Spark