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.
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/jsonAuthentication: Step by Step
1. Request an access token:
POST https://[organization].pluvo.com/oauth/token/
Content-Type: application/x-www-form-urlencoded2. Include these body parameters (form-urlencoded):
| Parameter | Value |
|---|---|
grant_type | client_credentials |
client_id | Your application's client ID |
client_secret | Your application's client secret |
scope | Space-separated list of scopes (e.g. users.read trainings.read events.read) |
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
| Property | Value |
|---|---|
| Token validity | 24 hours (86400 seconds) |
| Refresh mechanism | Not available for client_credentials. Request a new token before the current one expires. |
| Recommended pattern | Cache the token and request a new one when you receive a 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 } }"
}A successful response looks like:
{
"data": {
"paginatedUsers": {
"edges": [
{
"node": {
"id": "abc-123-...",
"name": "Jane Doe",
"email": "jane@example.com"
}
}
],
"count": 42
}
}
}Version Management
The Pluvo API is stable. Breaking changes are avoided. New fields are added without removing old ones. There is no explicit versioning of the GraphQL API. Deprecated fields are marked with @deprecated and include a reason with the recommended alternative.
Test Environment
There is no public sandbox. Use your own organization environment with a separate API client with limited permissions. For dedicated test environments, contact support.
Pagination Limits
All paginated queries have a maximum page size of 50 items. Requesting more than 50 will return an error or be capped to 50. Use cursor-based pagination to loop through larger datasets — see the Pagination page for details.
Rate Limits
Standard rate limits apply per API client. Excessive requests may be throttled. For bulk operations or peak traffic scenarios, contact support for specific arrangements.
Troubleshooting
| Problem | Cause | Solution |
|---|---|---|
| HTTP 301 redirect | Missing trailing slash | Add / at the end of the URL |
| HTTP 401 Unauthorized | Token expired or invalid | Request a new token via /oauth/token/ |
| HTTP 403 Forbidden | Insufficient scopes | Request a token with the required scope |
"errors" in response | GraphQL query error | Check the error message for field names and types |
Empty data response | No matching objects found | Verify your filter parameters (id, ref, email) |