OAuth 2.0 Server & Externe Applicaties

Sidefish fungeert als een volwaardige OAuth 2.0 Authorization Server (RFC 6749). Hiermee kunnen externe softwareleveranciers, integrators en CRM-pakketten (zoals BrokerCloud) veilig en gemachtigd communiceren met de Sidefish API namens een gebruiker of organisatie, zonder dat permanente API-sleutels of inloggegevens gedeeld hoeven te worden.

---

1. Ondersteunde OAuth 2.0 Flows

De OAuth 2.0 engine van Sidefish ondersteunt de volgende standaard grants:

1. Authorization Code Grant (Aanbevolen voor webapplicaties en CRM-integraties):
   • De gebruiker logt in bij Sidefish en geeft de externe app toestemming voor specifieke scopes.
   • De applicatie ontvangt een tijdelijke autorisatiecode en wisselt deze server-side om voor een access_token en refresh_token.
2. Client Credentials Grant:
   • Voor machine-to-machine communicatie tussen vertrouwde backend-services.
3. Refresh Token Grant:
   • Voor het automatisch vernieuwen van een verlopen access_token zonder dat de gebruiker opnieuw hoeft in te loggen.

---

2. OAuth 2.0 Endpoints

Alle OAuth 2.0 endpoints bevinden zich onder de basis-URL: https://sidefish.app/api/v1/oauth/v2/.

A. Autorisatie Endpoint (/oauth/v2/auth)

Start de toestemmingsflow voor de gebruiker:

• Methode: POST
• Pad: /api/v1/oauth/v2/auth

Parameter	Type	Beschrijving
client_id	Query / Body	Het unieke Client ID van uw OAuth-applicatie.
response_type	Query / Body	Altijd code voor de Authorization Code flow.
redirect_uri	Query / Body	De geregistreerde callback-URL van uw applicatie.
scope	Query / Body	Spatie-gescheiden lijst van gewenste rechten (bijv. customers:read sessionrequests:write).
state	Query / Body	Een unieke willekeurige tekenreeks ter preventie van CSRF-aanvallen.

B. Token Endpoint (/oauth/v2/token)

Wissel de ontvangen code om voor een geldig Bearer token:

• Methode: POST
• Pad: /api/v1/oauth/v2/token
• Content-Type: application/x-www-form-urlencoded

Request Voorbeeld (Authorization Code):

POST /api/v1/oauth/v2/token HTTP/1.1
Host: sidefish.app
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=UW_CLIENT_ID&client_secret=UW_CLIENT_SECRET&code=VERKREGEN_AUTH_CODE&redirect_uri=https%3A%2F%2Fuw-app.be%2Foauth%2Fcallback

Token Response (200 OK):

{
  "token_type": "Bearer",
  "access_token": "sf_at_8f1b2c3d4e5f60718293a4b5c6d7e8f9...",
  "refresh_token": "sf_rt_9a8b7c6d5e4f302110fedcba98765432...",
  "expires_in": 86400,
  "scope": "customers:read sessionrequests:write"
}

• Het access_token is standaard 24 uur (86.400 seconden) geldig.

Token Vernieuwen (Refresh Token):

POST /api/v1/oauth/v2/token HTTP/1.1
Host: sidefish.app
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&client_id=UW_CLIENT_ID&client_secret=UW_CLIENT_SECRET&refresh_token=UW_REFRESH_TOKEN

C. Token Intrekken (/oauth/v2/revoke)

Trek een actief token in wanneer een koppeling wordt verbroken of een gebruiker uitlogt:

• Methode: POST
• Pad: /api/v1/oauth/v2/revoke
• Content-Type: application/x-www-form-urlencoded

POST /api/v1/oauth/v2/revoke HTTP/1.1
Host: sidefish.app
Content-Type: application/x-www-form-urlencoded

token=sf_at_8f1b2c3d4e5f60718293...&client_id=UW_CLIENT_ID&client_secret=UW_CLIENT_SECRET

---

3. Fijnmazige Scopes

Sidefish dwingt strikte permissies af op basis van scopes. Vraag enkel de minimaal benodigde rechten aan:

Scope	Rechten
customers:read	Klantgegevens en contactfiches raadplegen en doorzoeken.
customers:write	Klanten aanmaken en bestaande klantgegevens bijwerken.
portfolios:read	Portefeuilles en contactgroepen uitlezen.
portfolios:write	Contactgroepen aanmaken of toewijzingen beheren.
sessionrequests:read	Status en antwoorden van uitgestuurde vragenlijsten en documenten inzien.
sessionrequests:write	Nieuwe vragenlijstverzoeken of ondertekenacties starten.
quicksigningsetup:read	Gegevens van voorbereide snelonderteken-acties opvragen.
quicksigningsetup:write	Snelondertekenacties voorbereiden en koppelen via deep-links.
users:read	Gegevens van de ingelogde gebruiker en organisatie raadplegen.

---

4. API-aanroepen met het Bearer Token

Plaats het verkregen access_token in de Authorization-header van elk volgend HTTP-verzoek:

curl -X GET "https://sidefish.app/api/v1/customers?limit=25" \
  -H "Authorization: Bearer sf_at_8f1b2c3d4e5f60718293a4b5c6d7e8f9..." \
  -H "Accept: application/json"

Bij een ontbrekende scope of verlopen token retourneert de API de statuscode 401 Unauthorized of 403 Forbidden met een JSON error payload.