Skip to content
LydieDevelopers
Menu

Authentication

Personal API tokens for scripts, OAuth 2.1 for apps and MCP clients, and what each kind of token may do.

View as Markdown

Every request sends a bearer token:

HTTP
Authorization: Bearer lyd_pat_...

Tokens work on the operation routes under https://api.lydie.co/v1 and on the MCP server at https://api.lydie.co/mcp. Everything else answers 401.

Personal API tokens

Use one for your own scripts and agents. Create it in Settings → Agents & API → Hosted API, or with Create an API token from a signed-in session.

  • The secret is lyd_pat_ followed by 43 characters. Lydie shows it once and stores only a hash.
  • Scopes: docs:read lets the token read, and docs:write lets it make changes. New tokens get both unless you choose read only.
  • Expiry: never, or after a number of days you choose.
  • Revoke it in the same settings page. It stops working at once.

What a token can do

A token acts as you, with your access to pages, and is limited to the workspace it was made for.

  • Pages, teamspaces and members of other workspaces answer 404 not_found, as if they did not exist.
  • An operation needs the token’s scope: queries need docs:read and changes need docs:write. A token without the scope gets 403 forbidden.
  • Some operations need a signed-in session in the Lydie app and refuse every token with 403. These include managing tokens and connected apps, creating a workspace, transferring ownership, leaving a workspace, and accepting or declining invitations. The reference marks them.

Changes made with a token are recorded as an agent acting for you. The document’s createdBy or updatedBy reads agent:api-token:<token id>:<your user id>. See Agent changes and undo.

OAuth 2.1

OAuth is for apps that act for other people, and for MCP clients. The person approves the app in Lydie, picks a workspace, and can narrow the scopes. MCP clients that support the MCP authorization spec do all of this themselves: give them https://api.lydie.co/mcp and they open the sign-in page.

Step Endpoint
Discovery GET /.well-known/oauth-protected-resource/mcp, GET /.well-known/oauth-authorization-server
Register the client POST /oauth/register (RFC 7591, public clients), or a client ID metadata document URL
Authorize GET /oauth/authorize with response_type=code, PKCE S256 (required), state, scope
Exchange and refresh POST /oauth/token (authorization_code, refresh_token)
Revoke POST /oauth/revoke (RFC 7009)

All endpoints are on https://api.lydie.co. A request to /mcp without a token gets 401 with a WWW-Authenticate header pointing at the discovery document.

  • Scopes are the same as for API tokens: docs:read docs:write.
  • Access tokens (lyd_oat_…) last one hour and have the same limits as API tokens.
  • Refresh tokens (lyd_ort_…) last 30 days and rotate on every use. Reusing an old refresh token revokes the whole grant.
  • Redirect URIs must be https, http on a loopback address (any port), or an app’s own scheme.
  • People see and disconnect apps under Settings → Agents & API → Connected apps.