# Finerlise auth.md

How an AI agent gets credentials to call the Finerlise API (https://www.finerlise.com/api/v1) on behalf of a user.

## Audience

Agents acting for a person who owns or administers a Finerlise Workspace and wants the agent to read that Workspace's forms and responses. Finerlise does not offer anonymous or self-registered agent access: every credential is issued by a person in the Workspace.

## Discovery

- Protected resource metadata (RFC 9728): https://www.finerlise.com/.well-known/oauth-protected-resource/api/v1
- Authorization server metadata (RFC 8414): https://www.finerlise.com/.well-known/oauth-authorization-server
- OpenAPI 3.1: https://www.finerlise.com/api/v1/openapi.json

An unauthenticated request to the API returns `401` with `WWW-Authenticate: Bearer resource_metadata="…"` pointing at the protected resource metadata.

## Registration methods

### 1. Workspace API key (recommended for agents)

1. Ask the user to open Finerlise, go to Settings → API keys (Owners and Admins only) and create a key for the agent.
2. The user copies the key (`fnr_live_…`, shown once) into the agent's secret store.
3. The key grants `responses:read`. The user can revoke it at any time from the same page.

### 2. OAuth 2.0 authorization code

For integrations that act for many users. Clients are registered by the Finerlise team; there is no dynamic client registration. Email support@finerlise.com to request a client.

- Authorization endpoint: https://www.finerlise.com/oauth/authorize
- Token endpoint: https://www.finerlise.com/api/oauth/token (`client_secret_basic` or `client_secret_post`)
- Revocation endpoint: https://www.finerlise.com/api/oauth/revoke
- Scopes: responses:read, forms:read, hooks:write
- Access tokens (`fnr_oat_…`) last one hour; refresh tokens are `fnr_ort_…`.

## Using the credential

Send it on every request as `Authorization: Bearer <token>`. Start with `GET https://www.finerlise.com/api/v1/me` to confirm which Workspace it acts as.

## Revocation

API keys: Settings → API keys → Revoke. OAuth apps: Settings → API keys → Connected apps → Disconnect, or call the revocation endpoint. Revoked credentials stop working immediately and return `401`.