> ## Documentation Index
> Fetch the complete documentation index at: https://help.nops.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Register an AWS account

> Registers one new AWS payer account and runs the Savings Analysis permission check. Used by the Clara Terraform provider after it creates the IAM role. Requires `aws-onboarding:create`, which this endpoint accepts and no other endpoint does: a key with only that permission cannot read, change, or delete anything. Returns `409` when the account already has an integration, with no detail about it. `verification.state` is `verified`, `partial` (Savings Analysis checks failed but cost and usage ingest works), `failed`, or `unavailable` (the check could not run; verify in the Clara UI).



## OpenAPI

````yaml /openapi.json post /v1/aws/onboarding
openapi: 3.1.0
info:
  title: nOps Public API
  version: 1.0.0
  description: >-
    Programmatic access to nOps cost, budgets, cost allocation, Explorer
    dashboards, AI optimization, MAP manager, business unit economics, contract
    tracker, seat tracking, reports, recommendations, feed, scheduled prompts,
    notifications, and the nOps Artifacts catalog. Authenticate with an API key
    (Bearer token). Available on Inform + Operate.
servers:
  - url: https://api.nops.io
    description: Production
security:
  - bearerApiKey: []
tags:
  - name: Recommendations
    description: Cost optimization recommendations.
  - name: Anomalies
    description: AWS cost anomaly detection.
  - name: Explorer
    description: Cost Explorer queries — summary, history, heatmap, and dimensions.
  - name: Budgets
    description: Budgets, planning grids, alerts, and exports.
  - name: Seat Tracking
    description: >-
      AI seat tracking projects — per-user spend, limits, provider
      configuration, limit requests, automation, and analytics.
  - name: Reports
    description: Saved reports — create, update, render, and send.
  - name: Feed
    description: Clara Feed runs and delivery history.
  - name: Scheduled prompts
    description: Scheduled Clara prompts and manual runs.
  - name: Notifications
    description: Schedule and manage notification deliveries.
  - name: Commitments
    description: Commitment inventory (reserved for future use).
  - name: Cost allocation
    description: Cost Allocation showbacks, rules, and spend analytics.
  - name: Explorer dashboards
    description: Explorer dashboard layouts and widgets.
  - name: AI optimization
    description: AI Optimization default dashboard and anomaly insights.
  - name: MAP Manager
    description: AWS Migration Acceleration Program (MAP) project tracking.
  - name: Business unit economics
    description: Business unit economics models, units, and portfolio summaries.
  - name: Contract tracker
    description: Enterprise contract tracking and burndown analytics.
  - name: Artifacts
    description: >-
      nOps-curated Skills and Artifacts (HTML and Markdown files): list,
      details, file download, and preview image. Read-only.
  - name: AWS onboarding
    description: >-
      Register a new AWS account from infrastructure as code. Create-only: the
      key cannot read, change, or delete existing integrations.
paths:
  /v1/aws/onboarding:
    post:
      tags:
        - AWS onboarding
      summary: Register an AWS account
      description: >-
        Registers one new AWS payer account and runs the Savings Analysis
        permission check. Used by the Clara Terraform provider after it creates
        the IAM role. Requires `aws-onboarding:create`, which this endpoint
        accepts and no other endpoint does: a key with only that permission
        cannot read, change, or delete anything. Returns `409` when the account
        already has an integration, with no detail about it.
        `verification.state` is `verified`, `partial` (Savings Analysis checks
        failed but cost and usage ingest works), `failed`, or `unavailable` (the
        check could not run; verify in the Clara UI).
      operationId: onboardAwsAccount
      parameters:
        - schema:
            type: string
            maxLength: 64
            description: >-
              Unique key for safe retries on write requests (required, max 64
              characters).
          required: true
          name: Idempotency-Key
          in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: JSON request body
              additionalProperties: true
            example:
              payerAccountId: '123456789012'
              name: Production payer
              roleArn: arn:aws:iam::123456789012:role/nops-integration-role-1234
              externalId: 3f1c2b7e-9d4a-4c5e-8a60-1b2c3d4e5f60
              permissionMode: minimal
              cur:
                bucketName: nops-cur-1234-123456789012
                reportName: nops_cur_1234_hourly
                s3Prefix: nops-cur
              cur2:
                enabled: true
                exportName: nops_cur2_1234_hourly
                s3Prefix: nops-cur2
      responses:
        '201':
          description: >-
            Registers one new AWS payer account and runs the Savings Analysis
            permission check. Used by the Clara Terraform provider after it
            creates the IAM role. Requires `aws-onboarding:create`, which this
            endpoint accepts and no other endpoint does: a key with only that
            permission cannot read, change, or delete anything. Returns `409`
            when the account already has an integration, with no detail about
            it. `verification.state` is `verified`, `partial` (Savings Analysis
            checks failed but cost and usage ingest works), `failed`, or
            `unavailable` (the check could not run; verify in the Clara UI).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
              example:
                data:
                  id: clxawsint01
                  status: active
                  name: Production payer
                  payerAccountId: '123456789012'
                  verification:
                    state: verified
                    roleAssumption: ok
                    failedChecks: []
                    message: null
        '401':
          description: Unauthorized — invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
              example:
                error:
                  code: forbidden_scope
                  message: 'API key is missing required scope: budgets:write'
                  request_id: 550e8400-e29b-41d4-a716-446655440000
        '403':
          description: Forbidden — insufficient permissions or entitlement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
              example:
                error:
                  code: forbidden_scope
                  message: 'API key is missing required scope: budgets:write'
                  request_id: 550e8400-e29b-41d4-a716-446655440000
      security:
        - bearerApiKey: []
components:
  schemas:
    PublicApiError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            request_id:
              type: string
          required:
            - code
            - message
            - request_id
      required:
        - error
  securitySchemes:
    bearerApiKey:
      type: http
      scheme: bearer
      description: >-
        API key from Settings → Security → API Keys. Pass as `Authorization:
        Bearer YOUR_API_KEY`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.