Integrations & Debug API¶

Base paths: /core/api/integrations and /core/api/communities/{community_id}/debug

This page covers two small groups of endpoints:

• Integrations - lets a RECreation user register credentials for an external partner platform (currently the GDBN flexibility-market platform, in its v2 and legacy v1 flavours), check that the connection works, and manage the partner-side webhooks and service authentication methods that GDBN uses to call back into RECreation. The /gdbn/... routes are thin authenticated proxies: RECreation logs in to GDBN with the stored credentials and forwards the request.
• Debug - a single, internal, super-user-only endpoint for overriding community flags.

For the data-exchange side of the GDBN integration (setpoints and flexibility offers that GDBN pushes into RECreation) see GDBN BeFlexible. Authentication of the calls on this page follows Authentication; paths are relative to the base URL described in Base URL & Conventions.

Endpoint summary¶

Concepts¶

Ownership. An integration belongs to the user who created it. Every route that takes {integration_id} only finds integrations owned by the caller; someone else's integration (or a non-existent one) returns 404. There is no admin override.

Providers. The provider field selects the partner API dialect:

The /gdbn/... routes work with both providers; any other provider returns 404 Not a GDBN integration. The request and response shapes are the same for both - only the upstream paths differ.

Status. status is one of pending, connected or error. It becomes connected (and last_connected_at is set) after a successful login test, and error (with status_detail) after a failed POST .../test or after any proxied call that GDBN rejects with 401.

Stored credentials. The partner password is encrypted at rest (Fernet, key INTEGRATIONS_ENCRYPTION_KEY) and is never returned by the API; responses only expose base_url and email.

Integration object¶

All of the endpoints below that return an integration use this shape.

Upstream mapping¶

For reference, this is what each proxy route calls on the partner platform. The call is authenticated with a bearer accessToken obtained from the partner login; on a partner 401 RECreation logs in again and retries once.

Errors from the partner¶

Failures reaching or authenticating against the partner are mapped to HTTP errors with a detail message:

Integrations¶

List Integrations¶

GET /core/api/integrations

Returns every integration owned by the calling user, ordered by creation time (oldest first).

Auth / permissions: any authenticated user. Only the caller's own integrations are returned.

No parameters.

Example

curl https://<host>/core/api/integrations \
  -H "Authorization: Bearer $TOKEN"

Response (abridged)

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "provider": "GDBN",
    "base_url": "https://gdbn.example/backendv2",
    "email": "manager@example.com",
    "community_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "status": "connected",
    "status_detail": null,
    "last_connected_at": "2026-03-10T09:30:00Z",
    "created_at": "2026-03-10T09:30:00Z"
  }
]

Create an Integration¶

POST /core/api/integrations

Registers credentials for a partner platform. RECreation first performs a real login against the partner (base_url + provider login path); only if that succeeds is the integration stored, with status connected.

Auth / permissions: any authenticated user. The integration is owned by the caller.

Example

curl -X POST https://<host>/core/api/integrations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "GDBN",
    "base_url": "https://gdbn.example/backendv2",
    "email": "manager@example.com",
    "password": "s3cret",
    "community_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  }'

Response (201 Created, abridged)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "provider": "GDBN",
  "base_url": "https://gdbn.example/backendv2",
  "email": "manager@example.com",
  "community_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "connected",
  "status_detail": null,
  "last_connected_at": "2026-03-10T09:30:00Z",
  "created_at": "2026-03-10T09:30:00Z"
}

Update an Integration¶

PATCH /core/api/integrations/{integration_id}

Changes any subset of the integration's fields. If the provider, base_url, email or password changes, the connection is re-tested (against the new provider when provider changes) before anything is saved.

Auth / permissions: any authenticated user, owner of the integration only.

Example

curl -X PATCH https://<host>/core/api/integrations/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"base_url": "https://gdbn.example/backendv2", "password": "new-s3cret"}'

Response (abridged)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "provider": "GDBN",
  "base_url": "https://gdbn.example/backendv2",
  "email": "manager@example.com",
  "community_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "connected",
  "status_detail": null,
  "last_connected_at": "2026-03-11T14:02:10Z",
  "created_at": "2026-03-10T09:30:00Z"
}

Delete an Integration¶

DELETE /core/api/integrations/{integration_id}

Deletes the integration and its stored (encrypted) credentials from RECreation.

Auth / permissions: any authenticated user, owner of the integration only.

Example

curl -X DELETE https://<host>/core/api/integrations/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer $TOKEN"

Response: 204 No Content (empty body).

Test an Integration¶

POST /core/api/integrations/{integration_id}/test

Logs in to the partner with the stored credentials and updates the integration's status accordingly.

Auth / permissions: any authenticated user, owner of the integration only.

Example

curl -X POST https://<host>/core/api/integrations/3fa85f64-5717-4562-b3fc-2c963f66afa6/test \
  -H "Authorization: Bearer $TOKEN"

Response (abridged, failed test)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "provider": "GDBN",
  "base_url": "https://gdbn.example/backendv2",
  "email": "manager@example.com",
  "community_id": null,
  "status": "error",
  "status_detail": "Invalid GDBN credentials",
  "last_connected_at": "2026-03-10T09:30:00Z",
  "created_at": "2026-03-10T09:30:00Z"
}

GDBN Services¶

These routes proxy to the partner platform and require an integration whose provider is GDBN or GDBN_V1 (otherwise 404 Not a GDBN integration). {service_id} is the partner-side service identifier (a string returned by the list call). See Errors from the partner for the statuses they can return.

List GDBN Services¶

GET /core/api/integrations/{integration_id}/gdbn/services

Returns the services (service offerings) the partner account has, as returned by GDBN, typically including each service's webhooks.

Auth / permissions: any authenticated user, owner of the integration only.

Example

curl https://<host>/core/api/integrations/3fa85f64-5717-4562-b3fc-2c963f66afa6/gdbn/services \
  -H "Authorization: Bearer $TOKEN"

Response (abridged; the body is passed through from GDBN)

[
  {
    "id": "svc-1",
    "name": "Flex service",
    "webhooks": [
      { "id": "wh-1", "url": "https://recreation.example/hooks/baseline", "event": "NEW_BASELINE" }
    ]
  }
]

GDBN Webhooks¶

Create GDBN Webhooks¶

POST /core/api/integrations/{integration_id}/gdbn/services/{service_id}/webhooks

Registers one or more webhooks on a partner service, so GDBN calls the given URL when the event occurs. The body is a JSON array, so several events can be registered in one call.

Auth / permissions: any authenticated user, owner of the integration only.

Example

curl -X POST https://<host>/core/api/integrations/3fa85f64-5717-4562-b3fc-2c963f66afa6/gdbn/services/svc-1/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {"url": "https://<host>/core/api/communities/7c9e6679-7425-40de-944b-e07fc1f90ae7/energy_management/offers/external/GDBN_BEFLEXIBLE", "event": "NEW_FLEXIBILITY_REQUEST"},
    {"url": "https://<host>/hooks/baseline", "event": "NEW_BASELINE"}
  ]'

Response (201 Created, abridged; passed through from GDBN)

[
  { "id": "wh-2", "url": "https://<host>/hooks/baseline", "event": "NEW_BASELINE" }
]

Update a GDBN Webhook¶

PATCH /core/api/integrations/{integration_id}/gdbn/webhooks/{webhook_id}

Changes the URL of an existing webhook.

Auth / permissions: any authenticated user, owner of the integration only.

Example

curl -X PATCH https://<host>/core/api/integrations/3fa85f64-5717-4562-b3fc-2c963f66afa6/gdbn/webhooks/wh-2 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://<host>/hooks/baseline-v2"}'

Response

{ "detail": "updated" }

Delete a GDBN Webhook¶

DELETE /core/api/integrations/{integration_id}/gdbn/webhooks/{webhook_id}

Deletes a webhook on the partner platform.

Auth / permissions: any authenticated user, owner of the integration only.

Example

curl -X DELETE https://<host>/core/api/integrations/3fa85f64-5717-4562-b3fc-2c963f66afa6/gdbn/webhooks/wh-2 \
  -H "Authorization: Bearer $TOKEN"

Response: 204 No Content (empty body).

Test a GDBN Webhook¶

POST /core/api/integrations/{integration_id}/gdbn/webhooks/test

Asks GDBN to send a test request to a webhook URL, to verify that the endpoint is reachable and that the service authentication works, optionally with a custom body.

Auth / permissions: any authenticated user, owner of the integration only.

Example

curl -X POST https://<host>/core/api/integrations/3fa85f64-5717-4562-b3fc-2c963f66afa6/gdbn/webhooks/test \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://<host>/hooks/baseline", "body": {"ping": true}}'

Response (illustrative; the body is whatever GDBN returns)

{ "status": 200, "message": "OK" }

GDBN Service Authentication¶

The auth method tells GDBN how to authenticate against your webhook endpoints (for example, how to obtain a token from RECreation before posting setpoints/offers). Two types are supported: JWT_TOKEN (GDBN logs in at a URL and then sends the token) and OAUTH2 (client credentials against a token URI). The same body schema is used to create, update and test.

Auth method body¶

Fields that are not sent (or are null) are dropped before the request is forwarded, so GDBN only receives the variant's own keys.

Get a GDBN Auth Method¶

GET /core/api/integrations/{integration_id}/gdbn/services/{service_id}/auth

Reads the auth method configured for a partner service.

Auth / permissions: any authenticated user, owner of the integration only.

Example

curl https://<host>/core/api/integrations/3fa85f64-5717-4562-b3fc-2c963f66afa6/gdbn/services/svc-1/auth \
  -H "Authorization: Bearer $TOKEN"

Response (abridged; passed through from GDBN)

{
  "id": "auth-1",
  "type": "OAUTH2",
  "tokenUri": "https://<keycloak-host>/realms/<your-realm>/protocol/openid-connect/token",
  "clientId": "gdbn-client"
}

Create a GDBN Auth Method¶

POST /core/api/integrations/{integration_id}/gdbn/services/{service_id}/auth

Creates the auth method for a partner service.

Auth / permissions: any authenticated user, owner of the integration only.

Example

curl -X POST https://<host>/core/api/integrations/3fa85f64-5717-4562-b3fc-2c963f66afa6/gdbn/services/svc-1/auth \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "OAUTH2",
    "tokenUri": "https://<keycloak-host>/realms/<your-realm>/protocol/openid-connect/token",
    "clientId": "gdbn-client",
    "clientSecret": "s3cret"
  }'

Response (201 Created, abridged; passed through from GDBN)

{ "id": "auth-1", "type": "OAUTH2" }

Update a GDBN Auth Method¶

PATCH /core/api/integrations/{integration_id}/gdbn/auth/{auth_method_id}

Updates an existing auth method, addressed by its own id (not the service id).

Auth / permissions: any authenticated user, owner of the integration only.

Example

curl -X PATCH https://<host>/core/api/integrations/3fa85f64-5717-4562-b3fc-2c963f66afa6/gdbn/auth/auth-1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "OAUTH2", "clientId": "gdbn-client", "clientSecret": "rotated-secret"}'

Response

{ "detail": "updated" }

Delete a GDBN Auth Method¶

DELETE /core/api/integrations/{integration_id}/gdbn/services/{service_id}/auth

Removes the auth method of a partner service (addressed by the service id).

Auth / permissions: any authenticated user, owner of the integration only.

Example

curl -X DELETE https://<host>/core/api/integrations/3fa85f64-5717-4562-b3fc-2c963f66afa6/gdbn/services/svc-1/auth \
  -H "Authorization: Bearer $TOKEN"

Response: 204 No Content (empty body).

Test a GDBN Auth Method¶

POST /core/api/integrations/{integration_id}/gdbn/auth/test

Asks GDBN to try an auth method definition (without saving it) to check that the login / token request works.

Auth / permissions: any authenticated user, owner of the integration only.

Example

curl -X POST https://<host>/core/api/integrations/3fa85f64-5717-4562-b3fc-2c963f66afa6/gdbn/auth/test \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "JWT_TOKEN",
    "loginUrl": "https://<host>/core/api/auth/login",
    "usernameField": "username",
    "username": "gdbn-service",
    "passwordField": "password",
    "password": "s3cret",
    "tokenField": "access_token"
  }'

Response (illustrative; the body is whatever GDBN returns)

{ "success": true }

Debug (internal)¶

Override Community Debug Fields¶

PUT /core/api/communities/{community_id}/debug

Directly overwrites the type and/or transaction_adjustment_tolerance columns of a community and returns the updated community.

Auth / permissions: platform super user only (verified account with the SUPER_USER role). Any other caller receives 403 Super users only.

Example

curl -X PUT https://<host>/core/api/communities/7c9e6679-7425-40de-944b-e07fc1f90ae7/debug \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "TEST", "transaction_adjustment_tolerance": 0.001}'

Response (abridged; CommunityResponseSchema)

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "name": "REC Matosinhos",
  "identifier": "rec-matosinhos",
  "type": "TEST",
  "status": "ACTIVE",
  "transaction_adjustment_tolerance": 0.001,
  "method_alloc_coeff": "FIXED",
  "start_date": "2026-01-01",
  "end_date": null
}