generated: '2026-08-06'
method: derived
source: openapi/altoira-partner-api-openapi.yml
docs: https://readme.altoira.com/docs/understand-the-oauth-process-to-alto
summary: >-
  Cross-cutting request/response semantics for the AltoIRA.com partner API,
  derived from the published OpenAPI 3.0.1 and the ReadMe developer hub. Alto
  operates a two-actor model: "manager context" operations authenticate with HTTP
  Basic credentials Alto assigns to the partner, and "user context" operations
  authenticate with an OAuth 2.0 bearer token obtained through an investor
  consent handoff. Several conventions that agent clients rely on — idempotency
  keys, pagination, rate-limit signaling, machine-readable error codes — are
  NOT part of this contract.
authentication:
  style: split by actor
  manager_context:
    scheme: HTTP Basic
    security_scheme: PlatformAuth
    description: Basic Auth credentials that were assigned to you by Alto.
    applies_to:
    - getOfferings
    - getOffering
    - createOffering
    - updateOffering
    - createDocument
    - createDocumentViaZip
    - enableOffering
    - getInvestment
    - investmentRefund
    - investmentCancel
    - investmentDistribution
    - issueNewCapitalCall
  user_context:
    scheme: HTTP Bearer
    security_scheme: UserAuth
    description: >-
      The OAuth token generated by POST /oauth/token, sent as
      "Authorization: Bearer".
    applies_to:
    - getUser
    - updateUser
  consent:
    scheme: OAuth 2.0 authorization code
    security_scheme: UserOauth
    authorization_endpoint: /oauth/authorize
    token_endpoint: /oauth/token
    refresh_endpoint: /oauth/token/refresh
    query_parameters:
    - client_id
    - response_type
    - scope
    - redirect_uri
    notes: >-
      response_type is always "code". redirect_uri must match the value Alto has
      on file for the partner. The flow declares an empty scopes map.
  detail: authentication/altoira-authentication.yml
idempotency:
  supported: false
  detail: >-
    No Idempotency-Key header, no idempotency parameter, and no idempotency
    discussion anywhere in the OpenAPI or the developer hub. This matters here
    more than for most APIs: investmentDistribution, investmentRefund and
    issueNewCapitalCall move real money out of a retirement account, and
    investmentDistribution documents a retryable 503. A partner retrying a
    timed-out distribution has no contract-level protection against a duplicate
    payment and must reconcile with getInvestment first.
pagination:
  supported: false
  detail: >-
    getOfferings ("List of all Offerings") declares no page, limit, offset or
    cursor parameter and no pagination envelope in its response. The collection
    is returned whole.
filtering_and_expansion:
  supported: false
  detail: >-
    No sparse-fieldset, expand, include or filter parameters. getInvestment
    accepts an optional investment_id query parameter to select a specific
    investment; createDocument accepts a `type` query parameter to classify an
    upload.
identifiers:
  style: partner-supplied external IDs plus Alto-issued numeric IDs
  external_id:
    description: >-
      The ID the partner uses internally to identify an Offering. It is the path
      key for nearly every offering and investment operation, which makes the
      partner the owner of the primary namespace.
    example: '12345'
  alto_user_id:
    description: >-
      Alto's identifier for an investor, obtained only through the OAuth handoff.
    note: >-
      Alto documents that a single customer may hold more than one Alto user ID,
      and advises partners to model a data structure supporting different Alto
      user IDs across different investments.
  alto_investment_id:
    description: Alto's numeric identifier for an investment, delivered on webhooks.
  platform_code:
    description: >-
      The partner's platform code, used in the investor-facing funding handoff
      URL.
versioning:
  scheme: none in the request path
  detail: >-
    No version segment, header or date parameter. The OpenAPI declares
    info.version 1.0.0 and the ReadMe hub publishes it under branch "0.1". There
    is no documented policy for how a breaking change would be communicated.
  detail_artifact: lifecycle/altoira-lifecycle.yml
content_types:
  request:
  - application/json
  - multipart/form-data
  response:
  - application/json
  detail: >-
    Document upload uses multipart/form-data, individually (createDocument) or as
    a zip archive (createDocumentViaZip).
errors:
  envelope: '{"error": true, "message": "..."} on distribution; {"message": "..."} on 401'
  rfc9457: false
  machine_readable_codes: false
  detail: errors/altoira-problem-types.yml
rate_limits:
  documented: false
  detail: >-
    No rate-limit headers, no quota documentation, and no 429 response anywhere
    in the contract or the developer hub.
request_tracing:
  request_id_header: not documented
async_events:
  webhooks: true
  detail: asyncapi/altoira-investments-webhooks.yml
  note: >-
    Investment lifecycle is tracked out-of-band. The webhook payload carries a
    `nonce` but Alto publishes no signature-verification scheme, so partners
    cannot cryptographically authenticate a delivery from the documentation
    alone.
environments:
  detail: sandbox/altoira-sandbox.yml
  servers:
  - url: https://altoira.sandbox.altoira.com
    description: Test API / Sandbox
  - url: https://www.altoira.com
    description: Production API