Developer docs

De Pluvo API geeft je programmatische toegang tot je leeromgeving. Beheer gebruikers, groepen, trainingen, inschrijvingen en certificaten vanuit je eigen systemen.

De API is gebaseerd op GraphQL. Je bepaalt zelf welke data je opvraagt of muteert, zonder overbodige velden. Authenticatie verloopt via OAuth 2.0 met client credentials. Webhooks houden je systemen real-time op de hoogte van wijzigingen.

Docs

Erste Schritte

Alle API-Anfragen werden über GraphQL verarbeitet.
Für die Authentifizierung ist ein gültiges OAuth-Token erforderlich.
Die Endpunkt-URL enthält Ihren Organisationsnamen.
Erforderliche Header: Authorization, Content-Type
Sie können mit Postman, Insomnia oder einem beliebigen GraphQL-Client testen.

API-Basis-URL

Für jede Organisation sieht der GraphQL-Endpunkt wie folgt aus:

https://[organization].pluvo.com/graphql/

Der abschließende Schrägstrich ist erforderlich. Ohne ihn schlagen Anfragen fehl oder werden umgeleitet.

Header

Setzen Sie für jede Anfrage die folgenden Header:

Authorization: Bearer <access_token>
Content-Type: application/json

Authentifizierung: Schritt für Schritt

1. Zugriffstoken anfordern:

POST https://[organization].pluvo.com/oauth/token/
Content-Type: application/x-www-form-urlencoded

2. Fügen Sie diese Body-Parameter hinzu (form-urlencoded):

grant_type: client_credentials

client_id: Die Client-ID Ihrer Anwendung

client_secret: Das Client-Secret Ihrer Anwendung

scope: Leerzeichengetrennte Liste der Scopes

3. Verwenden Sie das Token im Authorization-Header:

Authorization: Bearer <access_token>

Beispielantwort:

{
  "access_token": "abc123def456...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "users.read trainings.read events.read"
}

Token Lifecycle

Token validity: 24 hours (86400 seconds). No refresh mechanism for client_credentials. Request a new token before the current one expires. Cache the token and request a new one on 401 response, or proactively refresh after ~23 hours.

Your First Request

Once authenticated, try this query to verify your connection:

query {
  paginatedUsers(first: 3) {
    edges {
      node {
        id
        name
        email
      }
    }
    count
  }
}

Send it as a POST request:

{
  "query": "query { paginatedUsers(first: 3) { edges { node { id name email } } count } }"
}

Version Management

The Pluvo API is stable. Breaking changes are avoided. New fields are added without removing old ones. There is no explicit versioning. Deprecated fields are marked with @deprecated.

Pagination Limits

All paginated queries have a maximum page size of 50 items. Use cursor-based pagination for larger datasets — see the Pagination page for details.

Rate Limits

Standard rate limits apply per API client. For bulk operations or peak traffic, contact support.

Troubleshooting

HTTP 301 redirect: Missing trailing slash — add / at end of URL. HTTP 401: Token expired — request new token. HTTP 403: Insufficient scopes. errors in response: Check error message for field names. Empty data: Verify filter parameters.