> ## Documentation Index > Fetch the complete documentation index at: https://docs.userkit.dev/llms.txt > Use this file to discover all available pages before exploring further. # Start a social sign-in > Hosted mode only. Stores the in-flight authorization and answers with the URL to send the browser to. The `state` comes back to the caller because nothing on this surface rides a cookie: hold it (session storage is the usual place) and present it at the callback — that is what proves the two halves are one flow. PKCE is applied on every flow; the verifier never leaves the API. The **OAuth application belongs to the organization**: register it in your provider's console and store the credentials with `PUT /v1/organization/environments/{id}/oauth/{provider}`, so the consent screen carries your name. A **test** environment with nothing configured may fall back to a shared UserKit application; live never does. `redirect_uri` must be an absolute http(s) URL, and its origin must be in the publishable key's allowed-origins list when that list is set. Rate limited to 30 requests per hour per IP. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/contact-auth/oauth/{provider}/start openapi: 3.1.0 info: title: UserKit API version: 1.0.0 description: >- The HTTP surface of UserKit. Two planes share one API. The **staff plane** is what a human uses in the panel: users, organizations, roles, members, keys. The **customer plane** is what a developer's own product uses: contacts, identities, hosted or federated sign-in. Every error answers the same envelope — `{"error": {"code", "message"}}`. The `code` is a stable contract to branch on; the `message` is for a person and may change. servers: - url: '{baseUrl}' description: The API host. variables: baseUrl: default: https://api.userkit.dev description: Base URL of the API, no trailing slash. security: - sessionToken: [] tags: - name: Authentication description: >- Public sign-up, sign-in, two-factor and password recovery for staff accounts. - name: Session description: >- The active session: who the caller is, which organization they are in, and signing out. - name: Account description: The caller's own account — profile, password, sessions, avatar. - name: Two-factor description: >- TOTP setup, activation and recovery codes. Returns 501 when two-factor is unavailable on the server. - name: Organizations description: The organizations a user belongs to, and the active one. - name: Environments description: >- The live and test environments seeded with every organization, and their identity settings. - name: Members description: Memberships and invitations. - name: Roles description: Roles and the permission catalogue they draw from. - name: API keys description: Secret keys (`uk_sk_…`) and publishable keys (`uk_pk_…`). - name: Contacts (panel) description: >- The staff view of the customer plane. Reads take `?environment=` as an explicit view parameter. - name: Contacts (server) description: >- The machine surface, authenticated by an API key. The environment is the key's environment and cannot be named by the caller. - name: Customer plane description: >- Called from the developer's own pages with a publishable key: boot, magic link, and the contact's own session. - name: Hosted auth description: >- Sign-up, sign-in, verification and recovery for contacts, when UserKit owns the account. - name: System description: Health and the internal job callback. paths: /v1/contact-auth/oauth/{provider}/start: post: tags: - Hosted auth summary: Start a social sign-in description: >- Hosted mode only. Stores the in-flight authorization and answers with the URL to send the browser to. The `state` comes back to the caller because nothing on this surface rides a cookie: hold it (session storage is the usual place) and present it at the callback — that is what proves the two halves are one flow. PKCE is applied on every flow; the verifier never leaves the API. The **OAuth application belongs to the organization**: register it in your provider's console and store the credentials with `PUT /v1/organization/environments/{id}/oauth/{provider}`, so the consent screen carries your name. A **test** environment with nothing configured may fall back to a shared UserKit application; live never does. `redirect_uri` must be an absolute http(s) URL, and its origin must be in the publishable key's allowed-origins list when that list is set. Rate limited to 30 requests per hour per IP. operationId: startContactOAuth parameters: - $ref: '#/components/parameters/OAuthProvider' requestBody: required: true content: application/json: schema: type: object required: - publishable_key - redirect_uri properties: publishable_key: type: string redirect_uri: type: string format: uri description: >- Where the provider sends the browser back. Must match byte for byte at the callback. anonymous_id: type: string description: The visitor whose history this sign-in should inherit. attribution: $ref: '#/components/schemas/Attribution' responses: '200': description: The flow is open. content: application/json: schema: type: object properties: authorization_url: type: string format: uri description: Send the browser here. state: type: string description: '`uk_os_…`. Hold it and present it at the callback.' expires_at: type: string format: date-time '400': description: '`invalid_request` — `redirect_uri` is not an absolute http(s) URL.' content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '403': description: >- `origin_not_allowed` — the key does not accept redirects to this origin. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: '`unknown_provider` — this provider is not supported.' content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- `environment_not_hosted`, or `oauth_provider_not_configured` — this environment has no application for the provider. content: application/json: schema: $ref: '#/components/schemas/Error' '429': $ref: '#/components/responses/RateLimited' '501': description: >- `social_login_unavailable` — social sign-in is unavailable on the server. content: application/json: schema: $ref: '#/components/schemas/Error' security: [] components: parameters: OAuthProvider: name: provider in: path required: true description: >- The social provider. `google` today; adding one is a row and an implementation, never a migration. schema: type: string enum: - google schemas: Attribution: type: object description: >- First touch, captured on the visitor at first load and preserved through a merge. All fields optional; empty means unknown. properties: utm_source: type: - string - 'null' utm_medium: type: - string - 'null' utm_campaign: type: - string - 'null' utm_term: type: - string - 'null' utm_content: type: - string - 'null' referrer: type: - string - 'null' landing_page: type: - string - 'null' Error: type: object description: Every error in this API answers this envelope. properties: error: type: object properties: code: type: string description: Stable. Branch on this. message: type: string description: For a person. May change. required: - code - message required: - error example: error: code: forbidden message: your role does not allow this action responses: Unauthorized: description: >- `unauthorized` — missing, malformed or expired credential. A well-formed credential from the wrong family says so: "this endpoint expects a staff session token, not an organization API key". content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: >- `rate_limited` — too many requests. `Retry-After` carries the window in seconds. The counters are shared across instances. When that store cannot be reached each instance counts on its own instead: the limits get looser, never absent. headers: Retry-After: schema: type: integer description: Seconds until the window resets. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: sessionToken: type: http scheme: bearer description: >- A staff session token, `uk_st_…`. Minted by sign-up, sign-in or the two-factor exchange. ````