> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.helpyousponsor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Complete Box OAuth for file uploads

> Exchanges a Box authorization code for access and refresh tokens and stores them on the target client account. The endpoint is used after an admin authorizes Box for upload storage integration. Requires admin file access through `user.permissions`.



## OpenAPI

````yaml get /admin/box_response
openapi: 3.0.0
info:
  title: Gratona API
  description: >-
    REST API for the Gratona fundraising platform, including donor, donation,
    sponsorship, program, event, and integration workflows. Endpoints are
    organized by tag. Most endpoints require either a Passport bearer token or
    an issued API key — see the Security Schemes section.
  contact:
    name: Gratona Engineering
    url: https://gratona.com
    email: devs@gratona.com
  version: 1.0.0
servers:
  - url: https://api.gratona.com/v1
    description: Server Version 1.0.0
security: []
tags:
  - name: Auth
    description: >-
      Login, signup, logout, password reset, and email verification for admin
      users and donors.
  - name: Donors
    description: >-
      Donor records: CRUD, profile fields, household linkage, search, filters,
      merge, and duplicate detection.
  - name: Donations
    description: >-
      Individual donation records, recurring commitments, soft credits, refunds,
      designations, and exports.
  - name: Sponsorships
    description: >-
      Donor-to-entity sponsorship relationships, lifecycle transitions, and
      sponsorship-specific filters.
  - name: Entities
    description: >-
      Recipient records (children, families, projects, animals, etc.), their
      status, and entity-level fields.
  - name: Programs
    description: >-
      Program / campaign configuration: hierarchy, settings, and program-level
      metadata.
  - name: Forms
    description: >-
      Custom form builder (HysForm), form fields, standardized donor fields, and
      field migrations.
  - name: Trips
    description: >-
      Mission-trip management: trips, participants, budgets, tasks,
      e-signatures, fundraising milestones, and background checks.
  - name: Communications
    description: >-
      Email templates, SMS, newsletters, donor email manager, and per-donor
      notes.
  - name: Payments
    description: >-
      Payment-gateway management (Stripe, PayPal, Flutterwave, QuickBooks).
      Excludes inbound webhooks — see the Webhooks tag.
  - name: Reports
    description: Dashboards, analytics, scheduled reports, and exports.
  - name: Admin
    description: >-
      Client-account administration: users, groups/permissions, settings,
      integrations, and account lifecycle.
  - name: Donor Portal
    description: >-
      Endpoints consumed by the donor-facing portal (donor login, dashboard,
      donation history, messages).
  - name: Recipient Portal
    description: Endpoints consumed by the recipient-facing portal.
  - name: Public
    description: >-
      Unauthenticated public endpoints: donor signup, public trip pages,
      peer-to-peer campaigns, public checkout.
  - name: Webhooks
    description: >-
      Inbound webhooks from third parties (Stripe, PayPal, Flutterwave, Checkr,
      DropboxSign). Annotated minimally for reference; payload shapes are owned
      by the upstream provider.
  - name: Client
    description: Client
  - name: Email Settings
    description: Email Settings
  - name: Admin Dashboard
    description: Admin Dashboard
  - name: Historical Archived Updates
    description: Historical Archived Updates
  - name: Team & access
    description: Team & access
  - name: Files
    description: Files
  - name: Wrapped
    description: Wrapped
  - name: Donor SignUp
    description: Donor SignUp
  - name: Frontend
    description: Frontend
  - name: User
    description: User
paths:
  /admin/box_response:
    get:
      tags:
        - Files
      summary: Complete Box OAuth for file uploads
      description: >-
        Exchanges a Box authorization code for access and refresh tokens and
        stores them on the target client account. The endpoint is used after an
        admin authorizes Box for upload storage integration. Requires admin file
        access through `user.permissions`.
      operationId: 2ad9d3aa67ec39db0ee4eb4d75f87948
      parameters:
        - name: code
          in: query
          description: >-
            Required Box authorization code returned by the Box OAuth redirect.
            The controller exchanges this code with Box for tokens.
          required: true
          schema:
            type: string
          example: box_auth_code_123
        - name: client_id
          in: query
          description: >-
            Required Gratona client ID whose Box credentials and resulting OAuth
            tokens should be used and updated.
          required: true
          schema:
            type: integer
          example: 207
      responses:
        '200':
          description: Box connected.
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                    example: Successfully connected to Box.com
                type: object
        '400':
          description: Box returned an OAuth error.
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                    example: invalid_grant
                  error_description:
                    type: string
                    example: Authorization code has expired.
                type: object
        '422':
          description: Validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
      security:
        - bearerAuth: []
        - apiKeyAuth: []
components:
  schemas:
    ValidationErrorResponse:
      title: ValidationErrorResponse
      description: >-
        Returned with HTTP 422 when `Validator::make($data, $rules)` fails. The
        `errors` map is keyed by the failing field name; each value is an array
        of human-readable error messages for that field. Most controllers also
        include a top-level `status: error`.
      required:
        - errors
      properties:
        errors:
          description: >-
            Map of field name to array of validator error messages. Example:
            `{email: [The email field is required.], amount: [The amount must be
            a number.]}`.
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        status:
          description: Always the literal string `error`.
          type: string
          example: error
        message:
          description: >-
            Optional summary message — present on some endpoints, absent on
            others.
          type: string
          example: The given data was invalid.
          nullable: true
      type: object
  securitySchemes:
    bearerAuth:
      type: http
      description: Passport bearer token authentication for legacy admin sessions.
      scheme: bearer
      bearerFormat: JWT
    apiKeyAuth:
      type: apiKey
      description: Gratona API key sent with the compatibility header X-HYS-API-Key.
      name: X-HYS-API-Key
      in: header

````

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