Metronome Security API

openapi: 3.0.1
info:
  title: Metronome Alerts Security API
  version: 1.0.0
  description: '[Alerts](https://docs.metronome.com/connecting-metronome/alerts/) monitor customer spending, balances, and other billing factors. Use these endpoints to create, retrieve, and archive customer alerts. To view sample alert payloads by alert type, navigate [here.](https://docs.metronome.com/manage-product-access/create-manage-alerts/#webhook-notifications)'
servers:
- url: https://api.metronome.com
  description: Production server
security:
- bearerAuth: []
tags:
- name: Security
  description: '[Security](https://docs.metronome.com/developer-resources/security/) endpoints allow you to retrieve security-related data.'
paths:
  /v1/auditLogs:
    get:
      description: "Get a comprehensive audit trail of all operations performed in your Metronome account, whether initiated through the API, web interface, or automated processes. This endpoint provides detailed logs of who did what and when, enabling compliance reporting, security monitoring, and operational troubleshooting across all interaction channels.\n\n### Use this endpoint to:\n- Monitor all account activity for security and compliance purposes\n- Track configuration changes regardless of source (API, UI, or system)\n- Investigate issues by reviewing historical operations\n\n### Key response fields: \nAn array of AuditLog objects containing:\n- id: Unique identifier for the audit log entry\n- timestamp: When the action occurred (RFC 3339 format)\n- actor: Information about who performed the action\n- request: Details including request ID, IP address, and user agent\n- `resource_type`: The type of resource affected (e.g., customer, contract, invoice)\n- `resource_id`: The specific resource identifier\n- `action`: The operation performed\n- `next_page`: Cursor for continuous log retrieval\n\n### Usage guidelines:\n- Continuous retrieval: The next_page token enables uninterrupted log streaming—save it between requests to ensure no logs are missed\n- Empty responses: An empty data array means no new logs yet; continue polling with the same next_page token\n- Date filtering:\n    - `starting_on`: Earliest logs to return (inclusive)\n    - `ending_before`: Latest logs to return (exclusive)\n    - Cannot be used with `next_page`\n- Resource filtering: Must specify both `resource_type` and `resource_id` together\n- Sort order: Default is `date_asc`; use `date_desc` for newest first\n"
      operationId: getAuditLogs-v1
      summary: Get audit logs
      parameters:
      - $ref: '#/components/parameters/PageLimit'
      - $ref: '#/components/parameters/NextPage'
      - name: starting_on
        in: query
        description: RFC 3339 timestamp of the earliest audit log to return. Cannot be used with 'next_page'.
        required: false
        schema:
          type: string
          format: date-time
      - name: ending_before
        in: query
        description: RFC 3339 timestamp (exclusive). Cannot be used with 'next_page'.
        required: false
        schema:
          type: string
          format: date-time
      - name: sort
        in: query
        description: Sort order by timestamp, e.g. date_asc or date_desc. Defaults to date_asc.
        required: false
        schema:
          type: string
          enum:
          - date_asc
          - date_desc
      - name: resource_id
        in: query
        description: Optional parameter that can be used to filter which audit logs are returned. If you specify resource_id, you must also specify resource_type.
        required: false
        schema:
          type: string
      - name: resource_type
        in: query
        description: Optional parameter that can be used to filter which audit logs are returned. If you specify resource_type, you must also specify resource_id.
        required: false
        schema:
          type: string
      tags:
      - Security
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - next_page
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AuditLog'
                  next_page:
                    type: string
                    description: The next_page parameter is always returned to support ongoing log retrieval. It enables continuous querying, even when some requests return no new data. Save the next_page token from each response and use it for future requests to ensure no logs are missed. This setup is ideal for regular updates via automated processes, like cron jobs, to fetch logs continuously as they become available. When you receive an empty data array, it indicates a temporary absence of new logs, but subsequent requests might return new data.
                    nullable: true
  /v1/services:
    get:
      description: 'Gets Metronome''s service registry with associated IP addresses for security allowlisting and firewall configuration. Use this endpoint to maintain an up-to-date list of IPs that your systems should trust for Metronome communications. Returns service names and their current IP ranges, with new IPs typically appearing 30+ days before first use to ensure smooth allowlist updates.

        '
      operationId: getServices-v1
      summary: Get services
      tags:
      - Security
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - services
                properties:
                  services:
                    type: array
                    items:
                      $ref: '#/components/schemas/Service'
components:
  schemas:
    AuditLog:
      type: object
      required:
      - id
      - timestamp
      - request
      properties:
        id:
          type: string
        timestamp:
          type: string
          format: date-time
        actor:
          $ref: '#/components/schemas/Actor'
        request:
          type: object
          required:
          - id
          properties:
            id:
              type: string
            ip:
              type: string
            user_agent:
              type: string
        resource_type:
          type: string
        resource_id:
          type: string
        action:
          type: string
        status:
          type: string
          enum:
          - success
          - failure
          - pending
        description:
          type: string
    Actor:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: string
        email:
          type: string
        name:
          type: string
    Service:
      type: object
      required:
      - name
      - usage
      - ips
      properties:
        name:
          type: string
        usage:
          type: string
          enum:
          - makes_connections_from
          - accepts_connections_at
        ips:
          type: array
          items:
            type: string
  parameters:
    PageLimit:
      name: limit
      in: query
      description: Max number of results that should be returned
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
    NextPage:
      name: next_page
      in: query
      description: Cursor that indicates where the next page of results should start.
      required: false
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer