Authentication

The public REST API uses a Bearer JWT token. The token is obtained with a client_id and client_secret credential pair.

Flow

sequenceDiagram
  participant Client as Client system
  participant API as Knowspread REST API
  participant Space as CompanySpace credential

  Client->>API: POST /rest/v1/auth/token
  API->>Space: Verify client_id and client_secret
  Space-->>API: company_space_id
  API-->>Client: access_token + expires
  Client->>API: Authorization: Bearer access_token

Important properties

• The token is bound to company_space_id.
• Expiration is configurable with JWT_TOKEN_EXPIRY_IN_MINUTES.
• All other REST endpoints expect a valid Bearer token.
• The token does not replace domain validation. Endpoints still check whether the requested resource belongs to the company space.

Documentation still needed

• exact request and response examples,
• error states for invalid credentials,
• recommended refresh and retry pattern for integrators.