> ## Documentation Index > Fetch the complete documentation index at: https://docs.recurso.dev/llms.txt > Use this file to discover all available pages before exploring further. # Start an OAuth Login > Begin a Google or GitHub social login by redirecting the browser to the provider's authorize URL. Begins a social login. The server generates a CSRF `state` and a PKCE code verifier, binds them into a short-lived signed httpOnly cookie (`recurso_oauth_state`, scoped to `/auth/oauth`, valid for 10 minutes), and `302`-redirects to the provider's authorize URL. The provider later sends the browser back to [`GET /auth/oauth/{provider}/callback`](/api-reference/auth/oauth-callback), which finishes the login. Navigate a browser to this URL — do not call it from a server, since the state cookie must land in the same browser that completes the callback. Check which providers are available first with [`GET /auth/oauth/providers`](/api-reference/auth/oauth-providers). ## Path Parameters | Parameter | Type | Required | Description | | ---------- | ------ | -------- | -------------------------------------------------- | | `provider` | string | Yes | The provider to log in with: `google` or `github`. | ## Example Request ```bash theme={null} curl -i https://api.recurso.dev/auth/oauth/google/start ``` ## Example Response There is no response body. A successful call answers `302 Found` with the provider's authorize URL in `Location` and the state cookie in `Set-Cookie`: ```http theme={null} HTTP/1.1 302 Found Location: https://accounts.google.com/o/oauth2/v2/auth?client_id=...&code_challenge=...&code_challenge_method=S256&redirect_uri=https%3A%2F%2Fapi.recurso.dev%2Fauth%2Foauth%2Fgoogle%2Fcallback&response_type=code&scope=openid+email+profile&state=... Set-Cookie: recurso_oauth_state=...; Path=/auth/oauth; Max-Age=600; HttpOnly; Secure; SameSite=Lax ``` ## Errors | Status | Code | When | Fix | | ------ | ---------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `404` | `not_found` | `provider` is not `google`/`github`, or the provider's client id and secret are not configured. | Check [`GET /auth/oauth/providers`](/api-reference/auth/oauth-providers) and only offer providers with `enabled: true`. | | `500` | `internal_error` | The server could not generate the CSRF state. | Retry; if it persists, contact support. | Errors use the standard envelope — see [Errors](/api-reference/errors). ## OpenAPI ````yaml GET /auth/oauth/{provider}/start openapi: 3.1.0 info: title: Recurso API version: 1.0.0 description: | The Recurso billing engine REST API. Authenticate by passing your API key as a bearer token: Authorization: Bearer Obtain an API key by registering a tenant via `POST /auth/register`. All authenticated endpoints live under the `/v1` prefix. Mutating endpoints support idempotency via the `Idempotency-Key` header. license: name: MIT identifier: MIT servers: - url: https://billing.example.com description: >- Example deployment — substitute the base URL of your own Recurso deployment. security: - bearerAuth: [] tags: - name: System description: Health, version, and API metadata - name: Auth description: Tenant registration - name: Plans description: Product catalog plans - name: Customers description: Customer management - name: Subscriptions description: Subscription lifecycle - name: Invoices description: Invoices, PDFs, and Indian GST e-invoicing - name: Coupons description: Discounts - name: Usage description: Metered usage events - name: Credit Notes description: Customer credits - name: Quotes description: Quote-to-invoice lifecycle - name: Webhooks description: Webhook endpoint management and event feed - name: Analytics description: Revenue analytics - name: Checkout description: Public hosted checkout for invoices - name: Payments description: Payment order creation - name: Inbound Webhooks description: Receivers for payment-gateway callbacks (Razorpay, Stripe) - name: Customer Portal description: Customer-facing portal — magic-link auth and session-scoped data - name: Developer description: API key management - name: Account description: Tenant account settings - name: Finance description: Ledger accounts, entries, reconciliation, and revenue recognition - name: Settings description: Tax (GST) and e-invoicing (IRP) configuration - name: Consents description: Consent records for RBI-compliant recurring billing - name: Referrals description: Customer referral program - name: Gifts description: Gift subscriptions - name: Mandates description: UPI Autopay mandates - name: Offline Payments description: Virtual accounts and manually recorded payments - name: Organizations description: Multi-entity organizations grouping several tenants - name: Accounting description: QuickBooks / Xero accounting integrations - name: Churn description: Churn risk scoring and alerts - name: Cancel Flows description: Configurable retention flows shown at cancellation time - name: Dunning description: Dunning analytics and multi-channel dunning campaigns paths: /auth/oauth/{provider}/start: get: tags: - Auth summary: Begin an OAuth login (redirect to the provider) description: > Generates a CSRF `state` and a PKCE verifier, binds them into a short-lived signed httpOnly cookie (`recurso_oauth_state`, scoped to /auth/oauth), and 302-redirects to the provider's authorize URL. Unknown or disabled providers return 404. operationId: startOAuthLogin parameters: - name: provider in: path required: true schema: type: string enum: - google - github responses: '302': description: Redirect to the provider's authorize URL. Sets the state cookie. '404': $ref: '#/components/responses/NotFound' security: [] components: responses: NotFound: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/Error' schemas: Error: type: object required: - error properties: error: type: object description: Structured error detail. required: - code - message properties: code: type: string description: Stable machine-readable error code. examples: - validation_failed - unauthorized - forbidden - not_found - conflict - rate_limited - internal_error - invalid_api_key - key_mode_mismatch - over_refund - invoice_not_paid - invoice_already_paid message: type: string description: Human-readable explanation. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: >- Tenant API key obtained from `POST /auth/register` or `POST /v1/developer/keys`. ````