Archera OAuth API

openapi: 3.1.0
info:
  description: '### Welcome to the Archera.ai API documentation.

    Archera.ai empowers organizations to optimize cloud costs and automate cloud financial operations. Our API enables seamless integration with your internal tools, workflows, and reporting systems. With this API, you can programmatically access commitment plans, metrics, and more, unlocking the full potential of your cloud data.


    Whether you''re building custom dashboards, automating cost management, or integrating with third-party platforms, the Archera.ai API provides secure and reliable endpoints to help you achieve your goals.


    If you have questions or need support, please contact our team at support@archera.ai.


    ## API Key Access


    To use this API, you need an API key.


    ### How to Create an API Key

    1. Log in to the Archera.ai web application.

    2. Navigate to **User Settings > API Access**.

    <a href="https://app.archera.ai/settings?tab=api&section=user" target="_blank" rel="noopener noreferrer">Open Settings</a>

    3. Click **Create New API Key**.

    4. Copy and securely store your new API key.


    ### How to Use Your API Key

    Use the `x-api-key` header:


    ```bash

    curl -H ''x-api-key: YOUR_API_KEY'' https://api.archera.ai/v1/org/{org_id}/metrics?provider=aws

    ```


    Keep your API key secure. If you believe your key has been compromised, deactivate it in the web application and generate a new one.

    ### How to find your Organization ID

    1. Log in to the Archera.ai web application.

    2. Navigate to **User Settings > Organization**.

    3. Your Organization ID is displayed at the top of the page. You can also find it in the URL when visiting the Archera app `&orgId=<org_id>`


    '
  title: Archera.ai Commitment Plans OAuth API
  version: v1.0.0
tags:
- name: OAuth
  description: OAuth 2.0 authorization endpoints for third-party integrations
paths:
  /oauth/authorize:
    get:
      responses:
        default:
          $ref: '#/components/responses/DEFAULT_ERROR'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '405':
          description: Method not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      summary: Redirect to React consent page.
      description: "Query Parameters (handled by Authlib):\n    client_id: OAuth client identifier\n    redirect_uri: Where to redirect after authorization\n    response_type: Must be 'code'\n    scope: Space-separated list of requested scopes\n    state: CSRF protection token (optional but recommended)\n    code_challenge: PKCE code challenge\n    code_challenge_method: PKCE method (usually 'S256')\n\nReturns:\n    Redirect to React consent page with OAuth params and client info"
      tags:
      - OAuth
    post:
      responses:
        default:
          $ref: '#/components/responses/DEFAULT_ERROR'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '405':
          description: Method not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      summary: Handle user authorization decision from React consent page.
      description: "Query Parameters:\n    All OAuth params from GET (client_id, redirect_uri, state, etc.)\n\nForm Parameters:\n    confirm: 'yes' to authorize, 'no' to deny\n\nReturns:\n    Redirect to client with authorization code or error"
      tags:
      - OAuth
  /oauth/token:
    post:
      responses:
        default:
          $ref: '#/components/responses/DEFAULT_ERROR'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '405':
          description: Method not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      summary: Issue access tokens.
      description: "Form Parameters (authorization_code grant):\n    grant_type: Must be 'authorization_code'\n    code: Authorization code from /authorize\n    redirect_uri: Must match original request\n    client_id: OAuth client identifier\n    code_verifier: PKCE code verifier\n\nForm Parameters (refresh_token grant):\n    grant_type: Must be 'refresh_token'\n    refresh_token: Valid refresh token\n    client_id: OAuth client identifier\n\nReturns:\n    JSON response with access_token (JWT), refresh_token, expires_in, etc."
      tags:
      - OAuth
  /oauth/sessions:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OAuthSessionResponse'
        default:
          $ref: '#/components/responses/DEFAULT_ERROR'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '405':
          description: Method not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      summary: List all active OAuth sessions for the current user.
      description: 'Returns:

        List of active sessions including client info, creation time, and scope'
      tags:
      - OAuth
  /oauth/sessions/{token_id}:
    parameters:
    - in: path
      name: token_id
      required: true
      schema:
        type: string
        format: uuid
    delete:
      responses:
        '204':
          description: No Content
        default:
          $ref: '#/components/responses/DEFAULT_ERROR'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '405':
          description: Method not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      summary: Revoke a specific OAuth session by token ID.
      description: "Args:\n    token_id: UUID of the OAuth token to revoke\n\nReturns:\n    204 No Content on success\n    404 Not Found if session doesn't exist or doesn't belong to user"
      tags:
      - OAuth
  /oauth/revoke-all:
    post:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevokeAllSessionsResponse'
        default:
          $ref: '#/components/responses/DEFAULT_ERROR'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '405':
          description: Method not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      summary: Revoke all OAuth sessions (refresh tokens) for the current user across all clients.
      description: 'Returns:

        JSON with message and count of revoked sessions'
      tags:
      - OAuth
  /oauth/revoke:
    post:
      responses:
        default:
          $ref: '#/components/responses/DEFAULT_ERROR'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '405':
          description: Method not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      summary: Revoke an access token or refresh token.
      description: "Form Parameters:\n    token: The token to revoke (access_token or refresh_token)\n    token_type_hint: Optional hint about token type ('access_token' or 'refresh_token')\n\nReturns:\n    200 response (always returns 200 per RFC 7009, even for invalid tokens)"
      tags:
      - OAuth
  /oauth/register:
    post:
      responses:
        default:
          $ref: '#/components/responses/DEFAULT_ERROR'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '405':
          description: Method not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      tags:
      - OAuth
components:
  schemas:
    ApiErrorResponse:
      type: object
      properties:
        message:
          type: string
        detail: {}
        code:
          type:
          - string
          - 'null'
        url:
          type:
          - string
          - 'null'
        timestamp:
          type: string
        type:
          type: string
      required:
      - message
      - timestamp
      - type
    OAuthSessionResponse:
      type: object
      properties:
        token_id:
          type: string
          pattern: '[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\Z'
        client_name:
          type: string
        client_id:
          type: string
        created_at:
          type: integer
        scope:
          type: string
      required:
      - client_id
      - client_name
      - created_at
      - scope
      - token_id
      additionalProperties: false
    RevokeAllSessionsResponse:
      type: object
      properties:
        message:
          type: string
        count:
          type: integer
      required:
      - count
      - message
      additionalProperties: false
    Error:
      type: object
      properties:
        code:
          type: integer
          description: Error code
        status:
          type: string
          description: Error name
        message:
          type: string
          description: Error message
        errors:
          type: object
          description: Errors
          additionalProperties: {}
      additionalProperties: false
  responses:
    DEFAULT_ERROR:
      description: Default error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'