> ## 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. # Admin user login > Authenticates an admin user (a staff member of a client organization) and returns a Passport access token plus billing, entitlement and access snapshots for the organization. This is the entry point for the admin web app. The login flow also refuses logins for incomplete registrations, archived/decommissioned clients, inactive staff memberships, or users without an access role. A temporary organization lifecycle lock returns a retryable 409 response. ## OpenAPI ````yaml post /login 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: /login: post: tags: - Auth summary: Admin user login description: >- Authenticates an admin user (a staff member of a client organization) and returns a Passport access token plus billing, entitlement and access snapshots for the organization. This is the entry point for the admin web app. The login flow also refuses logins for incomplete registrations, archived/decommissioned clients, inactive staff memberships, or users without an access role. A temporary organization lifecycle lock returns a retryable 409 response. operationId: 76126a33c18c5825058ca1cc06b3d5c0 requestBody: description: Email + password credentials. required: true content: application/json: schema: required: - email - password properties: email: description: >- Admin user email. Validator rule: `required|string|email|max:255`. type: string format: email example: staff@gratona.com password: description: >- Admin user password. Validator rule: `required|string|min:6`. type: string format: password example: hunter2hunter2 type: object responses: '200': description: >- Login succeeded. Returns a bearer token, the authenticated user, a permissions map, and client billing snapshot. content: application/json: schema: properties: status: type: string example: success client_status: description: >- Legacy organization-billing classification returned for compatibility. This is not the organization lifecycle state and may include historical values such as `lead`, `due`, or `closed`. type: string example: active organization: description: Client organization display name. type: string example: Gratona Demo Org website: type: string example: https://demo.gratona.com nullable: true token: description: >- Laravel Passport bearer access token. Send as `Authorization: Bearer ` on subsequent requests. type: string example: eyJ0eXAiOiJKV1QiLCJhbGciOi... org_created_at: type: string format: date-time example: '2024-06-01T12:00:00Z' last_payment_date: type: string format: date-time example: '2026-04-10T08:00:00Z' nullable: true last_payment_amount: type: number format: float example: 39 nullable: true monthly_payment: description: Computed billing amount for the client. type: number format: float example: 39 user: $ref: '#/components/schemas/User' plan: type: string enum: - free - pro - growth - enterprise - custom - discounted example: pro pricing_tier: type: string enum: - legacy - new - custom example: legacy pricing_quote: description: >- Public pricing quote for the organization, including billable sponsorship units and the amount due in cents. properties: catalog_key: description: Catalog key. type: string example: gratona_public_2026 nullable: true catalog_name: description: Catalog name. type: string example: Gratona nullable: true assignment_source: description: Assignment source. type: string example: explicit_assignment nullable: true product: description: Product. type: string example: gratona nullable: true metric: description: Metric. type: string example: active_commitments nullable: true automatic_billing: description: Automatic billing. type: boolean example: true nullable: true plan: description: >- Effective plan summary with key, name and custom fields. type: object nullable: true usage_tier: description: Usage-derived tier summary. type: object nullable: true effective_tier: description: Tier applied after any contracted assignment. type: object nullable: true contracted_tier_key: description: Contracted tier key. type: string example: growth nullable: true application_fee_plan: description: Application fee plan. type: string example: growth nullable: true billable_units: description: Billable units. type: integer example: 100 nullable: true commitments: description: Commitments. type: integer example: 90 nullable: true relationship_only_sponsorships: description: Relationship only sponsorships. type: integer example: 5 nullable: true funded_recipient_relationships: description: Funded recipient relationships. type: integer example: 5 nullable: true sponsorship_units: description: Sponsorship units. type: integer example: 100 nullable: true pending_one_time_donations: description: Pending one time donations. type: integer example: 0 nullable: true total_due_cents: description: Total due cents. type: integer example: 3900 nullable: true currency: description: Currency. type: string example: USD billing_interval: description: Billing interval. type: string example: month nullable: true is_custom: description: Is custom. type: boolean example: false nullable: true is_chargeable: description: Is chargeable. type: boolean example: true nullable: true charge_skip_reason: description: Charge skip reason. type: string example: no_amount_due nullable: true pricing_review_needed: description: Pricing review needed. type: boolean example: false pricing_tier: description: Pricing tier. type: string example: new nullable: true ai_insight_limit: description: AI insight limit. type: integer example: 100 nullable: true ai_insight_limit_policy: description: AI insight limit policy. type: string example: soft nullable: true display: description: Formatted billing amounts and summary text. type: object nullable: true type: object entitlements: description: >- Resolved organization feature entitlements with live AI quota usage where available. Null when resolution fails. properties: version: type: integer example: 1 enforcement: type: string example: log catalog: type: string example: gratona_public_2026 nullable: true tier: type: string example: growth nullable: true tier_name: type: string example: Growth nullable: true quota_period: type: string enum: - one_time - billing_cycle example: billing_cycle degraded: type: boolean example: false features: description: >- Feature-key map. Entries include type, name, enabled, source and locked; quota, allowance, trial and tier metadata depend on the feature. type: object additionalProperties: type: object type: object nullable: true access_manifest: description: >- Server-derived access role and effective authority for the authenticated staff member. properties: version: type: integer example: 1 role: properties: id: type: integer example: 7 name: type: string example: Fundraising team is_full_access: type: boolean example: false version: type: integer example: 3 type: object nullable: true effective_access: description: >- Permission-key map containing allowed, source, area and level. type: object additionalProperties: type: object access_by_area: description: >- Area-key map containing id, area, allowed, level, source and reason. type: object additionalProperties: type: object restrictions: description: Active restrictions; absent when no role is resolved. type: array items: type: string example: disable_message_send_without_approval authority: type: array items: type: string example: donors_view can_manage: type: boolean example: false refresh_url: type: string example: /v1/admin/access/manifest type: object permissions: description: >- Effective permission map for the user's group; merged donor permissions are auto-added when `group_all` is granted. type: object additionalProperties: true type: object '401': description: Email / password did not match. content: application/json: schema: properties: message: type: string example: Invalid Credentials status: type: string example: error type: object '403': description: >- Login refused because onboarding is incomplete, the workspace is missing or closed, the staff membership is inactive, or no access role is assigned. content: application/json: schema: properties: message: type: string example: Finish setting up your account before signing in. status: type: string example: error user_id: description: Included only for incomplete onboarding. type: integer example: 1024 nullable: true stage: description: >- Current onboarding stage; included only for incomplete onboarding. type: integer example: 2 nullable: true type: object '409': description: >- Organization access is temporarily locked. Retry after the Retry-After header delay. headers: Retry-After: description: Seconds to wait before retrying authentication. schema: type: integer example: 30 content: application/json: schema: properties: message: type: string example: >- Organization access is temporarily unavailable. Try again shortly. status: type: string example: error retryable: type: boolean example: true type: object '422': description: The email or password failed validation. content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' security: [] components: schemas: User: title: User description: >- An admin user — staff member of a client organization. Authenticates via Laravel Passport (bearer JWT) for the admin web app, and may also issue API keys (via `ApiKey`) for server-to-server integrations. Permissions are stored as JSON keyed by feature; group membership (`group_id`) supplies a baseline permission set on top of the per-user override. required: - id - email - client_id properties: id: description: Internal user ID. type: integer format: int64 example: 1024 email: description: >- User email — also the login identifier. Unique across the whole users table. type: string format: email example: staff@gratona.com first_name: description: Given name. type: string example: Alex nullable: true last_name: description: Family name. type: string example: Morgan nullable: true phone: description: Optional phone number for SMS / call notifications. type: string example: '+15551234567' nullable: true client_id: description: >- Client (tenant) the user belongs to. Stored as string for historical reasons; numeric in practice. type: string example: '207' group_id: description: >- Permission group the user belongs to; supplies baseline permissions before the per-user override. type: integer format: int64 example: 4 nullable: true permissions: description: >- Per-user permission overrides as a JSON map keyed by permission slug. Values are typically the string `1` (granted) or absent. Merged with group permissions at request time. Example: `{group_all: 1, donor-42: 1}`. type: object nullable: true additionalProperties: true onboarding_status: description: >- Onboarding-flow stage marker. `3` = onboarding complete; lower values indicate the user is still in setup. type: string example: '3' nullable: true activated: description: >- Whether the account is activated (email verified / activation code redeemed). type: boolean example: true access_disabled_at: description: >- Administrative disable timestamp. Authorized admin payloads expose it so clients can distinguish disabled access from a pending mailbox-proof invitation. type: string format: date-time example: null nullable: true is_platform_admin: description: >- Server-resolved platform authority. Clients must treat false or missing as no platform authority and must not infer this grant from persisted roles or legacy ids. type: boolean example: false activation_code: description: Pending activation token — null after activation. type: string example: null nullable: true activated_at: type: string format: date-time example: '2024-06-15T10:00:00Z' nullable: true last_login: type: string format: date-time example: '2026-04-29T14:01:00Z' nullable: true email_verified_at: type: string format: date-time example: '2024-06-15T10:00:00Z' nullable: true created_at: type: string format: date-time example: '2024-06-15T09:50:00Z' updated_at: type: string format: date-time example: '2026-04-29T14:01:00Z' type: object 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 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.