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

Getting Started

All API requests are processed through GraphQL.
Authentication requires a valid OAuth token.
The endpoint URL contains your organization name.
Required headers: Authorization, Content-Type
You can test with Postman, Insomnia, or any GraphQL client.

API Base URL

For each organization, the GraphQL endpoint looks like this:

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

The trailing slash is required. Without it, requests will fail or redirect.

Headers

Set the following headers for each request:

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

Authentication: Step by Step

1. Request an access token:

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

2. Include these body parameters (form-urlencoded):

grant_type: client_credentials

client_id: Your application's client ID

client_secret: Your application's client secret

scope: Space-separated list of scopes

3. Use the token in the Authorization header:

Authorization: Bearer <access_token>

Example response:

{
  "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.