OAuth 2.1 och API för utvecklare

Wellfish är en OAuth 2.1-auktoriseringsserver och MCP-server. Discovery, klientregistrering, flöden, tokens och anrop mot REST-API:et.

Wellfish är en OAuth 2.1-auktoriseringsserver och en MCP-server. Samma token fungerar mot REST-API:et och MCP-servern. Sidan vänder sig till dig som bygger en integration eller ett eget verktyg.

Miljö	Issuer	MCP-server
Produktion	`https://app.wellfish.se`	`https://app.wellfish.se/api/mcp`
Staging	`https://staging.wellfish.se`	`https://staging.wellfish.se/api/mcp`

Staging har egna konton. Be din Wellfish-kontakt om ett testkonto.

Discovery

Dokument	URL
Auktoriseringsserverns metadata (RFC 8414)	`{issuer}/.well-known/oauth-authorization-server`
OpenID Connect discovery (samma innehåll)	`{issuer}/.well-known/openid-configuration`
Protected resource metadata för MCP (RFC 9728)	`{issuer}/.well-known/oauth-protected-resource/api/mcp`
JSON Web Key Set	`{issuer}/api/oauth/jwks`

Endpoints: {issuer}/api/oauth/authorize, /api/oauth/token, /api/oauth/revoke och /api/oauth/register (dynamisk klientregistrering).

MCP-servern

MCP-servern talar Streamable HTTP och kräver en bearer-token. Ett anrop utan token får 401 med en WWW-Authenticate-header som pekar på resursmetadatan. Så hittar Claude, Claude Code och Codex auktoriseringsservern och registrerar sig själva.

Svar på ett anrop utan tokenhttp

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://app.wellfish.se/.well-known/oauth-protected-resource/api/mcp", scope="wellfish.read offline_access"

Varje MCP-verktyg kräver wellfish.read. Alla verktyg är läsande. Se Verktyg och data.
Kopplingen är knuten till användarens företag och når det företaget och alla dotterbolag under det. Wellfish-administratörer har inget ankarföretag och anger companyId i varje anrop. Verktyget list_companies visar vad en koppling når.
Sessionskakan accepteras aldrig på MCP-servern. Bara bearer-token.

Skaffa en klient

Det finns två vägar.

Dynamisk registrering

Öppen för alla (RFC 7591). MCP-klienter gör det automatiskt. Skicka POST {issuer}/api/oauth/register:

POST /api/oauth/registerjson

{
  "client_name": "Mitt verktyg",
  "redirect_uris": ["https://mittverktyg.example.com/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_method": "client_secret_basic",
  "scope": "wellfish.read offline_access"
}

Regler:

redirect_uris måste vara https://, eller http://localhost och http://127.0.0.1 för native-appar. Porten ignoreras för loopback, så valfri port fungerar vid körning. En loopback-adress gör klienten till native automatiskt.
grant_types: bara authorization_code och refresh_token. Standard är authorization_code.
scope: wellfish.read, wellfish.write och offline_access. Standard är wellfish.read offline_access.
token_endpoint_auth_method: none, client_secret_basic (standard) eller client_secret_post.
Svaret innehåller client_id och, för konfidentiella klienter, client_secret.
En registrering som aldrig godkänns av en användare tas bort efter 90 dagar.
Gräns: 10 registreringar per timme och IP-adress.

Klient registrerad av Wellfish

För integratörer. Be din Wellfish-kontakt. Det är den enda vägen till client_credentials, som binds till ett företag och dess dotterbolag. Du får klient-id och hemlighet en gång. Hemligheten kan roteras på begäran.

Authorization code (för en användares räkning)

Standard OAuth 2.1:

Skicka användaren till /api/oauth/authorize

Med response_type=code, PKCE med code_challenge_method=S256 (krävs), redirect_uri, scope och state. Lägg till resource=https://app.wellfish.se/api eller resource=https://app.wellfish.se/api/mcp om ditt bibliotek skickar resource indicators. Båda är registrerade.

Användaren loggar in och godkänner

Användaren loggar in i Wellfish om det behövs, ser ditt klientnamn och de begärda behörigheterna, och skickas tillbaka med code och state.

Byt koden mot tokens på /api/oauth/token

Med grant_type=authorization_code, code, code_verifier, redirect_uri och dina klientuppgifter.

Tokens:

Token	Livslängd
Access token	60 minuter.
Refresh token	30 dagar, med rotation. Varje förnyelse ger en ny refresh token. Den gamla slutar fungera efter 30 sekunder.

Begär offline_access för att få en refresh token. En död refresh token svarar invalid_grant. Förnyelsen kontrollerar att användaren finns kvar, får logga in och fortfarande når företaget.

Client credentials (ett system, ingen användare)

POST /api/oauth/tokenhttp

POST /api/oauth/token HTTP/1.1
Host: app.wellfish.se
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=wf_...&client_secret=...&scope=wellfish.read%20wellfish.write

Token agerar som en företagsanvändare för det företag klienten är bunden till, med dess dotterbolag.

Anropa REST-API:et med en token

Skicka Authorization: Bearer <access_token>. Token bär företaget, så varje endpoint under /api/company/... fungerar precis som för en inloggad användare i det företaget. En token agerar på ett företag. Behöver du flera företag: hämta en token per företag, eller använd MCP-verktygen, som tar companyId.

wellfish.read krävs för GET, wellfish.write för alla andra metoder. Saknad behörighet svarar 403 med {"error":"insufficient_scope"}.
Vad token får se avgörs av rollen bakom den, exakt som för en inloggad användare.
API-referensen finns i Swagger.

Fel

Standardiserade OAuth-felkoder: invalid_request, invalid_client, invalid_grant, invalid_scope, unauthorized_client, access_denied, insufficient_scope och invalid_target (okänd resource). Dynamisk registrering svarar invalid_redirect_uri eller invalid_client_metadata med en error_description.

Återkallelse

Användare återkallar en koppling under Anslutna appar på sin profilsida. Klienter kan återkalla tokens på /api/oauth/revoke. Återkallelsen kontrolleras vid varje anrop, så en återkallad token slutar fungera direkt.