Arcadia API Keys API

openapi: 3.2.0
info:
  description: Plug API
  title: Plug API Keys API
  version: 2.0.0
servers:
- url: https://api.arcadia.com
security:
- OAuth2: []
tags:
- name: API Keys
paths:
  /apiKeys:
    get:
      description: Returns a paginated list of API keys within the caller's organization, scoped to the Business Units the caller is permitted to access.
      operationId: list-api-keys
      parameters:
      - description: Zero-based page index (0..N)
        in: query
        name: page
        schema:
          type: integer
          default: 0
      - description: The size of the page to be returned
        in: query
        name: size
        schema:
          type: integer
          default: 20
      - description: 'Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.'
        in: query
        name: sort
        schema:
          type: array
          items:
            type: string
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicPagedPlugApiKeyResource'
          description: OK
      summary: List API Keys
      tags:
      - API Keys
    post:
      description: Creates a new API key for the caller's organization, optionally scoped to one or more Business Units.
      operationId: create-api-key
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicPlugApiKeyRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicPlugApiKeyResource'
          description: OK
      summary: Create API Key
      tags:
      - API Keys
      parameters:
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
  /apiKeys/{clientId}:
    delete:
      description: Permanently deletes an API key, revoking its ability to authenticate.
      operationId: delete-api-key
      parameters:
      - in: path
        name: clientId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      responses:
        '200':
          description: OK
      summary: Delete API Key
      tags:
      - API Keys
    patch:
      description: Partially updates an API key. Only the fields supplied in the request body are changed; omitted fields are left as-is.
      operationId: update-api-key
      parameters:
      - in: path
        name: clientId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiKeyBusinessUnitPatchRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicPlugApiKeyResource'
          description: OK
      summary: Update API Key
      tags:
      - API Keys
  /apiKeys/{clientId}/events:
    get:
      description: Returns a paginated list of the change events recorded against a single API key, such as creation and business unit assignment updates.
      operationId: list-api-key-events
      parameters:
      - in: path
        name: clientId
        required: true
        schema:
          type: string
      - description: 'A search query string. See [this page](ref:searching) for more information.


          The searchable fields for this endpoint are: createdAt, eventType, fieldName'
        in: query
        name: search
        required: false
        schema:
          type: string
      - description: Zero-based page index (0..N)
        in: query
        name: page
        schema:
          type: integer
          default: 0
      - description: The size of the page to be returned
        in: query
        name: size
        schema:
          type: integer
          default: 20
      - description: 'Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.'
        in: query
        name: sort
        schema:
          type: array
          items:
            type: string
      - $ref: '#/components/parameters/arcVersionInHeaderParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicPagedPlugApiKeyEventResource'
          description: OK
      summary: List API Key Events
      tags:
      - API Keys
components:
  schemas:
    PublicPlugApiKeyEventResource:
      required:
      - clientId
      - createdAt
      - createdBy
      - eventType
      - fieldName
      - id
      - newValue
      - oldValue
      type: object
      properties:
        clientId:
          type: string
          description: The unique identifier of the API key this event was recorded against.
        createdAt:
          type: string
          description: A timestamp indicating when the event occurred.
          format: date-time
        createdBy:
          type: string
          description: User or system responsible for the event.
        eventType:
          type: string
          description: The type of event, indicating whether the API key was created or updated.
          enum:
          - CREATED
          - UPDATED
        fieldName:
          type:
          - string
          - 'null'
          description: The name of the field that was changed. `null` for creation events.
        id:
          type: string
          description: A unique identifier for the event.
        newValue:
          type:
          - string
          - 'null'
          description: The value of the field after the change. `null` for creation events.
        oldValue:
          type:
          - string
          - 'null'
          description: The value of the field before the change. `null` for creation events.
      description: An array of API key event objects.
    ApiKeyBusinessUnitPatchRequest:
      type: object
      properties:
        businessUnitIds:
          type: array
          description: The unique identifiers of the Business Units to assign to the API key, replacing any existing assignments.
          items:
            type: string
            description: The unique identifiers of the Business Units to assign to the API key, replacing any existing assignments.
    BusinessUnitRef:
      required:
      - id
      - name
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the business unit.
        name:
          type:
          - string
          - 'null'
          description: The name of the business unit. `null` for business units outside the caller's scope.
      description: The business units assigned to this user. `name` will be `null` for business units the caller is not assigned to.
    PublicPlugApiKeyRequest:
      required:
      - name
      type: object
      properties:
        businessUnitIds:
          type:
          - array
          - 'null'
          description: The unique identifiers of the Business Units to assign to the API key. If omitted, the API key is assigned no Business Units.
          items:
            type:
            - string
            - 'null'
            description: The unique identifiers of the Business Units to assign to the API key. If omitted, the API key is assigned no Business Units.
        name:
          maxLength: 255
          minLength: 0
          type: string
          description: The name for the API key.
    PageMetadata:
      required:
      - number
      - size
      - totalElements
      - totalPages
      type: object
      properties:
        number:
          type: integer
          format: int64
        size:
          type: integer
          format: int64
        totalElements:
          type: integer
          format: int64
        totalPages:
          type: integer
          format: int64
      description: Specifies which page of results to return; this is 0-indexed
    PublicPlugApiKeyResource:
      required:
      - businessUnits
      - clientId
      - clientSecret
      - createdAt
      - createdBy
      - name
      type: object
      properties:
        businessUnits:
          type: array
          description: Business units associated with this API key.
          items:
            $ref: '#/components/schemas/BusinessUnitRef'
        clientId:
          type: string
          description: The unique identifier for the API key.
        clientSecret:
          type:
          - string
          - 'null'
          description: The secret associated with the API key. If null, the secret could not be decrypted and the client must be re-created.
        createdAt:
          type: string
          description: The timestamp indicating when this API key was created.
          format: date-time
        createdBy:
          type: string
          description: User or system responsible for creating the API key.
        name:
          type: string
          description: The name for the API key.
    PublicPagedPlugApiKeyResource:
      required:
      - apiKeys
      - page
      type: object
      properties:
        apiKeys:
          type: array
          description: An array of API key objects.
          items:
            $ref: '#/components/schemas/PublicPlugApiKeyResource'
        page:
          $ref: '#/components/schemas/PageMetadata'
    PublicPagedPlugApiKeyEventResource:
      required:
      - apiKeyEvents
      - page
      type: object
      properties:
        apiKeyEvents:
          type: array
          description: An array of API key event objects.
          items:
            $ref: '#/components/schemas/PublicPlugApiKeyEventResource'
        page:
          $ref: '#/components/schemas/PageMetadata'
  parameters:
    arcVersionInHeaderParam:
      name: Arcadia-Version
      in: header
      example: '2024-02-21'
      description: The Arcadia-Version for the request
      required: true
      schema:
        type: string
        default: '2024-02-21'
  securitySchemes:
    OAuth2:
      type: oauth2
      description: This API uses OAuth2 with the client credentials flow using the ['Create an Access Token'](ref:create-access-token) endpoint. API keys can be retrieved from the [Dashboard](https://dashboard.arcadia.com/).
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: /oauth2/token
x-provenance:
  method: harvested
  publisher: Arcadia
  source: https://docs.arcadia.com/openapi/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)