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

# Start Google login

> Returns the URL a client should navigate to in order to begin Google OAuth.
The URL points to `GET /auth/google`, which redirects the browser to Google's
consent screen. After the user consents, the browser is redirected back through
`/auth/google/callback` and session cookies are set.

For cross-origin SSO, pass `returnTo` (must be allowlisted, or registered to
your app via `clientId`) — the callback then redirects to
`returnTo?pid_code=...` with a one-time exchange code instead of the wallet.

First-time users always land on the PID picker after authenticating
(`POST /v1/auth/claim` creates the permanent `<handle>@pid` identity) —
handles are only ever chosen there, never up front. Returning logins
continue straight to a session.




## OpenAPI

````yaml /openapi.yaml post /auth/login
openapi: 3.0.3
info:
  title: PeridotID API
  version: 0.1.0
  description: >
    Gaming Identity Platform — Authentication, Identity, and Profile for the
    Peridot ecosystem.


    ## Base URL

    All endpoints are prefixed with `/v1`.


    | Environment | Base URL |

    |---|---|

    | Production | `https://api.pid.peridotvault.com/v1` |

    | Local dev | `http://localhost:3300/v1` |


    ## Authentication

    Authentication is **cookie-based**. After a successful Google sign-in the
    API sets two

    `HttpOnly` cookies:


    - `pid_access` — short-lived JWT access token (15 min), sent on every
    request.

    - `pid_refresh` — long-lived rotating refresh token (30 days), only sent to
    `/v1/auth`.


    Browsers handle these automatically; non-browser clients must send

    `Cookie: pid_access=<token>` on each request and call `/v1/auth/refresh`
    before the

    access token expires.
  contact:
    name: PeridotID
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://api.pid.peridotvault.com/v1
    description: Production
  - url: http://localhost:3300/v1
    description: Local development
security: []
tags:
  - name: auth
    description: Login, logout, token refresh, and machine (client-credentials) tokens
  - name: identity
    description: The user's identity across products
  - name: profile
    description: The user's public profile
  - name: wallet
    description: >
      The user's wallet, associated with their PID. **Deprecated (V3 surface)**
      — preserved

      for existing clients, backed by `linked_address` chain accounts. Use
      `/account` and

      the smart account instead.
  - name: account
    description: >-
      PeridotID account — owns chain accounts (smart account PDA, legacy linked
      address)
  - name: fiat
    description: |
      The internal IDR fiat ledger: balances, statements, sends, and money-in.
      Top-ups enter through a hosted DOKU Checkout page (no Sub-Account) and
      credit the internal ledger once the payment is corroborated. Any identity
      can send to any identity (escrow/payouts). Fees: global 0.1% (min Rp100,
      no cap) plus optional per-app fees that stack and credit the app. Bank
      withdrawals (redemption) are disabled for now.
  - name: apps
    description: |
      Third-party apps ("Sign in with PeridotID"): client_id, allowed origins,
      optional backend secret, ledger callbacks (deferred), and a per-app fee
      schedule. Owner-scoped — a non-owner gets 404. App backends authenticate
      server-side with `POST /v1/auth/token` (client credentials).
  - name: credentials
    description: >
      Signing authorities (secp256r1 passkeys). Google OAuth proves identity; a

      passkey authorizes the wallet. The first credential registers freely; each
      additional

      credential requires approval by an existing credential
      (existing-credential approval rule).
  - name: permissions
    description: >
      EVM permission grants (scoped P-256 session keys, WHITEPAPER.md §10).
      Validation is pure

      hygiene + canonical id/challenge computation; submission-time account
      binding

      is enforced by the relay path.
  - name: session-keys
    description: >
      SVM gameplay sessions (Ed25519 session keys in isolated PDAs,
      WHITEPAPER.md §11).

      Validation is pure hygiene + canonical address/challenge computation;

      submission-time vault binding is enforced by the relay path.
  - name: openapi
    description: Machine-readable API specification
paths:
  /auth/login:
    post:
      tags:
        - auth
      summary: Start Google login
      description: >
        Returns the URL a client should navigate to in order to begin Google
        OAuth.

        The URL points to `GET /auth/google`, which redirects the browser to
        Google's

        consent screen. After the user consents, the browser is redirected back
        through

        `/auth/google/callback` and session cookies are set.


        For cross-origin SSO, pass `returnTo` (must be allowlisted, or
        registered to

        your app via `clientId`) — the callback then redirects to

        `returnTo?pid_code=...` with a one-time exchange code instead of the
        wallet.


        First-time users always land on the PID picker after authenticating

        (`POST /v1/auth/claim` creates the permanent `<handle>@pid` identity) —

        handles are only ever chosen there, never up front. Returning logins

        continue straight to a session.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                returnTo:
                  type: string
                  format: uri
                  description: Cross-origin URL to return to with a pid_code
                clientId:
                  type: string
                  description: Registered app id (binds the pid_code to your app)
            examples:
              sso:
                summary: Third-party SSO login
                value:
                  returnTo: https://mygame.dev/callback
                  clientId: pidapp_0123456789abcdef0123456789abcdef
      responses:
        '200':
          description: Google authorization URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
              example:
                url: http://localhost:3300/v1/auth/google
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    LoginResponse:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: Navigate here to start Google sign-in
      example:
        url: http://localhost:3300/v1/auth/google
    ApiError:
      type: object
      required:
        - statusCode
        - message
      properties:
        statusCode:
          type: integer
        message:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
  responses:
    BadRequest:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            statusCode: 400
            message:
              - >-
                handle must be 3-20 chars: lowercase letters, numbers,
                underscore
    RateLimited:
      description: Too many requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            statusCode: 429
            message: 'ThrottlerException: Too Many Requests'

````

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