Introduction

GraphQL Interface

• The Pluvo API is a GraphQL-based interface for managing users, trainings, events, and more.
• Authentication is handled via an OAuth token based on client_id and client_secret.
• Webhooks provide real-time updates about enrollments, statuses, and more.
• Endpoint: https://[organization].pluvo.com/graphql/

The Pluvo API enables external systems such as HRM platforms and integration tools to programmatically communicate with the Pluvo platform.

Authentication

Access to the API requires an OAuth token that you request via:

POST https://[organization].pluvo.com/oauth/token/

Important:

• Endpoint requires trailing slash /
• Headers: Content-Type: application/x-www-form-urlencoded
• Body parameters:
  • grant_type=client_credentials
  • client_id=...
  • client_secret=...
  • scope=... (e.g., users.read trainings.write)

A valid token is included as a Bearer token in API requests:

Authorization: Bearer <your_token>

Access tokens are valid for 24 hours. After expiry, request a new token using the same credentials. There is no refresh token flow for client_credentials — simply request a new token.

Scopes and Access Levels

Scopes control what your API client can access. Request only the scopes you need.

Multiple scopes can be requested in a single token by separating them with spaces: scope=users.read users.write trainings.read

API Endpoint

All requests are made to:

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

The trailing slash is required. Requests without it will return a redirect or error.

GraphQL: Brief Overview

The Pluvo API implements a full GraphQL interface. You determine which fields you retrieve or update, ensuring minimal payloads and maximum flexibility.

Example query:

query user($ref: String!) {
  user(ref: $ref) {
    ref
    name
    email
    isActive
  }
}

The ref serves as a unique identifier within your own system. You can determine this value yourself when creating an object, as long as it remains unique within the entity.

Error Handling

GraphQL errors are returned in the response body with HTTP status 200. Always check the errors array:

{
  "data": null,
  "errors": [
    {
      "message": "User not found",
      "locations": [{"line": 2, "column": 3}],
      "path": ["user"]
    }
  ]
}

Common error scenarios:

• Invalid or expired token — HTTP 401. Request a new token.
• Insufficient scope — Error message indicates which scope is required.
• Object not found — null result with error in errors array.
• Validation error — Detailed message about which field failed validation.

Webhooks

Pluvo supports webhooks for real-time notifications about:

• User changes (created, updated, deleted)
• Training and course completion
• Enrollment status changes
• Portfolio and certificate events
• Group changes

Webhook configuration is done through the admin interface of your organization's Pluvo environment. Each webhook request contains an HMAC signature for verification.

See the Webhooks page for a full list of events and payload examples.