> ## Documentation Index > Fetch the complete documentation index at: https://docs.buckspay.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Social identity -> Stellar key > Signer-proxy endpoint. The BFF (`createSignerProxyRoute({ provider: 'web3auth', ... })`) forwards this request to the facilitator's `/auth/social` with the server-held API key injected. The facilitator verifies the provider identity token, derives or recovers the user's Stellar key, and returns it. **Never call the facilitator's `/auth/social` directly from the browser.** Use the BFF route: the SDK's `@buckspay/signers/social` posts to your same-origin BFF which proxies the call. The request body is provider-specific (Web3Auth / web3auth verifier). The response `publicKey` is a Stellar G-address (ed25519 StrKey). ## OpenAPI ````yaml /api-reference/openapi.json post /auth/social openapi: 3.1.0 info: title: Buckspay Facilitator & BFF API version: 0.2.0 description: >- HTTP wire contract for the Buckspay SDK. The SDK calls these endpoints internally via `@buckspay/relayer`; this reference is for teams building their own BFF relay route or calling the facilitator from server-side code. All facilitator endpoints require the `x-api-key` header. **The API key is a server-side secret - it must only appear in BFF or server-side code and must never be shipped to a browser bundle.** Use `createRelayRoute` and `createSignerProxyRoute` from `@buckspay/nextjs` to build compliant BFF handlers. servers: - url: '{facilitatorUrl}' description: >- Buckspay facilitator (all endpoints). Set via BUCKSPAY_FACILITATOR_URL on the server. variables: facilitatorUrl: default: https://facilitator.buckspay.xyz description: Base URL of the Buckspay facilitator service. security: - FacilitatorApiKey: [] tags: - name: Relay description: >- Submit a signed Soroban authorization entry for gasless relaying to the Stellar network. - name: Fee description: >- Quote the fee-token amount required for gas-in-token (token gas mode) before building the forward() invocation. - name: Account State description: Read on-chain state for classic G-addresses and contract C-addresses. - name: Onboarding description: >- Build and submit the sponsored onboarding transaction; deploy passkey smart-accounts and policy session-accounts. - name: Auth description: >- Signer-proxy for social and email authentication. The BFF forwards these requests to the facilitator; provider secrets remain server-side. - name: Swap description: >- Quote a gasless EVM token swap. Requires `swapChain` to be configured in the relayer. paths: /auth/social: post: tags: - Auth summary: Social identity -> Stellar key description: >- Signer-proxy endpoint. The BFF (`createSignerProxyRoute({ provider: 'web3auth', ... })`) forwards this request to the facilitator's `/auth/social` with the server-held API key injected. The facilitator verifies the provider identity token, derives or recovers the user's Stellar key, and returns it. **Never call the facilitator's `/auth/social` directly from the browser.** Use the BFF route: the SDK's `@buckspay/signers/social` posts to your same-origin BFF which proxies the call. The request body is provider-specific (Web3Auth / web3auth verifier). The response `publicKey` is a Stellar G-address (ed25519 StrKey). operationId: postAuthSocial requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AuthRequest' example: idToken: verifier: buckspay-google responses: '200': description: Identity verified. Returns the derived Stellar public key. content: application/json: schema: $ref: '#/components/schemas/AuthKeyResponse' '400': description: Identity token invalid or expired. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: auth_invalid '401': description: Invalid or missing API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: >- Signer proxy not configured (BUCKSPAY_FACILITATOR_URL or BUCKSPAY_FACILITATOR_API_KEY missing on the BFF server). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: signer_proxy_not_configured components: schemas: AuthRequest: type: object additionalProperties: true description: >- Provider-specific authentication payload. The BFF (`createSignerProxyRoute`) validates only that the body is a JSON object and proxies it transparently to the facilitator. Fields are provider-specific (social: `idToken` + `verifier`; email: `email` + `code`). AuthKeyResponse: type: object required: - publicKey - provider properties: publicKey: allOf: - $ref: '#/components/schemas/StellarPublicKey' description: >- Derived Stellar G-address for this identity. Stable across sessions for the same provider + user. provider: type: string description: Provider identifier (e.g. `google`, `email`). expiresAt: type: integer description: >- Unix timestamp (seconds) after which the derived key session should be refreshed. Omitted if the provider does not issue expiring sessions. description: >- Successful auth response. Mirrors the SDK `AuthDetails` type from `@buckspay/core`. The response is a transparent proxy of the facilitator's body. ErrorResponse: type: object required: - error properties: error: type: string description: >- Machine-readable error code. SDK error codes (e.g. `RELAYER_REJECTED`, `SESSION_POLICY_VIOLATION`) or raw facilitator codes (e.g. `auth_expired`, `simulation_failed`) depending on context. message: type: string description: >- Optional human-readable detail. Never log raw upstream messages - they may contain addresses or sensitive information. details: type: object description: >- Optional structured validation errors (present on BFF-level schema failures). description: >- Error body returned on non-2xx responses. The `error` field maps to a `BuckspayErrorCode` or a raw facilitator error string (see `mapFacilitatorError` in `@buckspay/relayer`). StellarPublicKey: type: string pattern: ^G[A-Z2-7]{55}$ description: Stellar classic public key (G-address, 56-character StrKey). securitySchemes: FacilitatorApiKey: type: apiKey in: header name: x-api-key description: >- Server-held API key. Injected by the BFF (`createRelayRoute` / `createSignerProxyRoute` from `@buckspay/nextjs`). This key must only appear in server-side code and must never be shipped to a browser bundle. ````