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

> Documentation Index
> Fetch the complete documentation index at: https://docs.wellfish.se/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth 2.1 och API för utvecklare

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.

```http title="Svar på ett anrop utan token"
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](/mcp/verktyg/).
- 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`:

```json title="POST /api/oauth/register"
{
  "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:

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.
2. **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`.
3. **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)

```http title="POST /api/oauth/token"
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](https://app.wellfish.se/swagger/index.html).

## 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.

Source: https://docs.wellfish.se/mcp/oauth/index.mdx