> ## Documentation Index > Fetch the complete documentation index at: https://docs.fluid.app/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > For new direct REST integrations, use the v2026-04 surfaces. The @fluid-app FairShare SDK continues to use its own published public-v2025-06 contract. > Authenticate with the header Authorization: Bearer ; public storefront read endpoints require no auth. > Lists use cursor pagination via the page[cursor] and page[limit] query params; follow meta.pagination.next_cursor until it is null. > Never use /api/company/v1 or /api/v1 paths, page/per_page params, or offset pagination — they are legacy. > The OpenAPI specs under api-reference/ are the authoritative contracts; prefer them over prose when in doubt. api-reference/storefront-v2026-04.yaml covers the v2026-04 storefront surface (/api/v202604/... paths); api-reference/auth-v0.yaml covers the unversioned auth surface (/api/... paths — authentication, MFA, social auth, and token exchange); api-reference/checkout-v2026-04.yaml covers the v2026-04 checkout surface (/api/checkout/v2026-04/... paths — carts, cart auth, discounts, items, subscriptions, orders, enrollments, and store config); api-reference/public-v2025-06.yaml covers the Public SDK surface used by the @fluid-app FairShare SDK, including its parallel cart lifecycle, browser integrations, versioned payment callbacks, unversioned public utilities, and the cart price-override operation; api-reference/payment-v2026-04.yaml covers the v2026-04 payment gateway admin surface (/api/payment/v2026-04/... paths, bearer-authenticated — gateway CRUD, gateway purchase/authorize/$0-verify, transaction list/show and capture/void/credit, and merchant payment configuration); api-reference/payments-v2026-04.yaml covers the v2026-04 cart payment surface (/api/payments/v2026-04/carts/{cart_token}/... paths, authenticated by the cart token in the path with no bearer — payment-method selection, VGS card tokenization, 3D Secure verification, and PayPal/Braintree/Klarna/Apple Pay flows); api-reference/commerce-v2026-04.yaml covers the v2026-04 commerce order-editing surface (/api/v202604/orders/{order_id}/edits paths, bearer-authenticated — post-checkout order edits that atomically insert items and add adjustments/discounts, with an optional dry-run preview); api-reference/webhooks-v0.yaml covers the unversioned webhooks surface (/api/... paths — webhook registration, delivery payloads, callback registrations, company events, and webhook/callback schemas). > Successful responses wrap the resource payload alongside a top-level integer status and a meta object. # Redirect to Apple OAuth > Generate an Apple OAuth URL for redirect-based authentication. `fluid_shop` must be supplied in practice — this operation returns `422` without it — even though it is declared as an optional parameter, because the requirement is enforced by the action rather than by parameter validation. Treat it as mandatory when calling. It is placed in the OAuth `state` (alongside a server-issued nonce, cached for replay rejection) so the callback can resolve the company. Apple returns to a bare redirect URI, so without it the shop is lost and white-label customers are locked out. The response mode is fixed server-side to `form_post` (Apple POSTs directly to the callback rather than redirecting), so it is not a request parameter. ## OpenAPI ````yaml /api-reference/auth-v0.yaml get /api/social_auth/apple openapi: 3.1.0 info: title: Fluid Auth API version: v0 description: >- Authentication, MFA, social auth, impersonation, and token exchange endpoints. contact: email: support@fluid.app license: name: Proprietary identifier: LicenseRef-Proprietary servers: - url: https://api.fluid.app - url: https://{company}.fluid.app description: Production server with company subdomain variables: company: default: myco description: Company subdomain security: [] tags: - name: auth-token description: Short-lived auth-token minting for the current user company. - name: authentication description: >- Email MFA login, company switching, JWT-based "me" lookups, and public company branding. - name: confirm-visitor description: Visitor token confirmation. - name: impersonation description: Root-admin company impersonation (start and exit). - name: multi-factor-authentications description: MFA record creation and verification-code checks. - name: single-sign-ons description: SSO-flow aliases of the authentication MFA and lookup endpoints. - name: social-auth description: >- Google, Facebook, and Apple OAuth URLs, callback handling, and Apple account linking. - name: switch-role description: Switch the current admin user between admin and rep roles. - name: token-exchange description: Exchange and refresh JWTs and user-company tokens. paths: /api/social_auth/apple: get: tags: - social-auth summary: Redirect to Apple OAuth description: >- Generate an Apple OAuth URL for redirect-based authentication. `fluid_shop` must be supplied in practice — this operation returns `422` without it — even though it is declared as an optional parameter, because the requirement is enforced by the action rather than by parameter validation. Treat it as mandatory when calling. It is placed in the OAuth `state` (alongside a server-issued nonce, cached for replay rejection) so the callback can resolve the company. Apple returns to a bare redirect URI, so without it the shop is lost and white-label customers are locked out. The response mode is fixed server-side to `form_post` (Apple POSTs directly to the callback rather than redirecting), so it is not a request parameter. operationId: auth_v0_social_auth_apple parameters: - name: fluid_shop in: query required: false description: >- Company subdomain the sign-in belongs to, carried through the OAuth round-trip in `state`. Omitting it returns `422` — Apple sign-in cannot resolve a company without it. schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/SocialAuthUrl' '422': description: fluid_shop was omitted or blank. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: [] components: schemas: SocialAuthUrl: description: OAuth provider URL for redirect-based authentication type: object additionalProperties: false required: - provider - auth_url - redirect_uri properties: provider: description: >- Provider key this URL belongs to (e.g. `google`, `facebook`, `apple`). type: string auth_url: description: >- Fully-formed provider authorization URL to redirect the user to; carries the server-issued OAuth `state`. type: string format: uri redirect_uri: description: >- Callback URI the provider returns to after the user authorizes; must match the value registered with the provider. type: string format: uri meta: $ref: '#/components/schemas/Meta' ErrorResponse: type: object additionalProperties: false required: - error_message - errors - meta properties: error_message: description: >- Human-readable summary of what went wrong, safe to surface to the caller. type: string errors: $ref: '#/components/schemas/ErrorBag' description: >- Structured per-field or per-issue detail behind `error_message`; shape varies (see `ErrorBag`) and is `null` when no structured detail is available. meta: $ref: '#/components/schemas/Meta' description: Response metadata (request id and generation timestamp). Meta: type: object properties: request_id: description: > Opaque per-request identifier echoed on the response; `null` when the request was not assigned one. Quote it when reporting an issue so support can correlate server-side logs. type: - string - 'null' timestamp: description: Server time the response was generated, as an ISO 8601 date-time. type: string format: date-time ErrorBag: description: >- Validation errors keyed by field, a list of errors, a single error message, or null when no structured error details are available. anyOf: - type: string - type: array items: $ref: '#/components/schemas/ErrorValue' - type: object additionalProperties: $ref: '#/components/schemas/ErrorValue' - type: 'null' ErrorValue: description: A validation or API error value. anyOf: - type: string - type: array items: type: string - type: object additionalProperties: $ref: '#/components/schemas/JsonValue' JsonValue: description: >- Any valid JSON value for provider, integration, theme, metadata, or other dynamic payloads whose keys are not fixed by the API contract. anyOf: - type: string - type: number - type: boolean - type: 'null' - type: array items: $ref: '#/components/schemas/JsonValue' - type: object additionalProperties: $ref: '#/components/schemas/JsonValue' ````