Cherished Book Auth API

openapi: 3.2.0
info:
  title: Cherishedbook Com Auth API
  version: 2.2.0
  description: 'Operations tagged Auth across 2 of this provider''s published API definitions: public.yaml, cherishedbook-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: /api/v1
- url: https://app.cherishedbook.com/api/v1
  description: Absolute base stated in https://www.cherishedbook.com/llms.txt (POST https://app.cherishedbook.com/api/v1/auth/device)
security:
- bearerAuth: []
tags:
- name: Auth
paths:
  /auth/device:
    post:
      summary: Start connecting (device flow)
      description: 'Begin the RFC 8628 device authorization flow. Requires no credential — this is how an assistant obtains one.

        Show the person `verification_uri_complete`, ask them to open it and approve, then poll `/auth/token` with the `device_code` every `interval` seconds until it returns a token.

        Approving requires signing in, which is also how we verify the person''s email address — so a memorial created with the resulting token is never asked to verify again.'
      operationId: startDeviceAuthorization
      security: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                client_name:
                  type: string
                  maxLength: 100
                  description: What to call your app on the approval screen, e.g. "Claude Desktop".
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - device_code
                - user_code
                - verification_uri
                - verification_uri_complete
                - expires_in
                - interval
                - message
                properties:
                  device_code:
                    type: string
                    description: Secret. Send to /auth/token. Never show this to the person.
                  user_code:
                    type: string
                    description: Short code the person reads or types, e.g. ABCD-2345.
                  verification_uri:
                    type: string
                  verification_uri_complete:
                    type: string
                    description: Give the person this link — the code is already in it.
                  expires_in:
                    type: integer
                  interval:
                    type: integer
                    description: Seconds to wait between polls.
                  message:
                    type: string
        '429':
          description: Too many codes requested from this address
      tags:
      - Auth
    servers:
    - url: /api/v1
  /auth/token:
    post:
      summary: Collect the token
      description: 'Exchange an approved `device_code` for a personal token. Poll no faster than `interval` seconds.

        Errors follow RFC 8628: `authorization_pending` means keep waiting, `slow_down` means you are polling too fast, `access_denied` means the person declined, `expired_token` means start again. The token is handed over once — store it.'
      operationId: collectDeviceToken
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - device_code
              properties:
                device_code:
                  type: string
      responses:
        '200':
          description: Approved
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - access_token
                - token_type
                - scope
                properties:
                  access_token:
                    type: string
                  token_type:
                    type: string
                  scope:
                    type: string
        '400':
          description: Not ready, declined, expired, or already collected
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                - message
                properties:
                  error:
                    type: string
                    enum:
                    - authorization_pending
                    - slow_down
                    - access_denied
                    - expired_token
                    - invalid_grant
                  error_description:
                    type: string
                  message:
                    type: string
      tags:
      - Auth
    servers:
    - url: /api/v1
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API token, sent as `Authorization: Bearer <token>`.

        A personal token is obtained through the device flow (`POST /auth/device`), or by hand from Connected apps in account settings. Rate limited to 20 requests/minute.

        A business token is created by a Business Admin in Business settings → API tokens, is shown once, and scopes to that organization. Rate limited to 50 requests/minute.

        '
x-refined-from:
- public.yaml
- cherishedbook-com-openapi.yml