Integration API tokens

The integration API connects your organization’s systems (HR, ERP, BI) to Eduvem: automatic registration and enrollment, report extraction, certificate downloads and more. All access happens through tokens created by the administrator.

Creating and managing tokens

• Create several named, independent tokens - one per integrated system is best practice. Each one can be revoked without affecting the others.
• The token value is shown only once, at creation. Store it in your organization’s secrets vault: if it’s lost, the way forward is to delete the token and create another.
• Some data requires extra permission granted on the token: certificate downloads, the enrollment audit history, the reports and, in classes with enrollment management, the decision on requests (Enrollments (write)). Grant only what the integration actually uses. To create, update or delete participants through the API, the token needs Users (write); to create or change classes, content versions, groups and roles, see Writing classes, content versions, groups and roles through the API.
• To change the scopes of a token you already created, use the edit permissions icon in the token list.
• Webhooks are bound to the token that set them up: deleting the token, or removing its Reports (read) permission, stops its webhooks. When replacing a token, the integration team must reactivate the webhooks with the new token before you delete the old one.

Editing a token’s permissions

A token’s permissions can be changed after it is created, without replacing the token: click the pencil icon (Edit permissions) on the token’s row. The dialog opens with the current permissions already checked.

• Adding a permission asks for confirmation: since the token is already in use, the integration gets access to the new data immediately, on its next call.
• Removing a permission saves directly, with no confirmation.
• The Platform permission comes with every token and cannot be unchecked.
• If another administrator changed the same token while the dialog was open, the change is refused and the list is refreshed: review it and try again.

What the integration does

Registering and updating participants (individually and in bulk), managing groups and roles, enrollments and state changes (approve, deny, cancel, reactivate), listing and downloading certificates as PDF, reports (per-class summary and per-enrollment export), the catalog of classes and content, and the ranking.

On enrollment via API, the participant can be identified by email or CPF - if they don’t exist yet, the record is created automatically.

Writing participants through the API

The Users (write) permission lets the token create, update, change the status of and delete participants through the API (POST /integrations/users, POST /integrations/users/multiple, PUT /integrations/users/{uuid}, PUT /integrations/users/{uuid}/status/{status} and DELETE /integrations/users/{uuid}). It is always available in the permissions list, is never checked by default and is not included in the Platform permission.

• Without it, these calls receive a 403 error (insufficientScope). Reading participants is unchanged and stays available to any token.
• Tokens that already wrote participants were granted the permission when the platform was upgraded. Any other token needs an administrator to check Users (write) in Edit permissions.
• Enrolling a person who does not exist yet, through the class or group enrollment endpoints, also needs Users (write), on top of the class or group permission.
• Changing the email or setting the password of a person who holds an administrator, publisher, observer or tutor role, through PUT /integrations/users/{uuid}, also needs Staff login. See Staff login.

Writing classes, content versions, groups and roles through the API

Four permissions control the write calls in these areas. All of them are always available in the permissions list, are never checked by default and are not included in the Platform permission. Read calls (GET) are unchanged.

Permission	What it allows
Classes (write)	Create and update classes (POST /integrations/courseClasses/create, PUT /integrations/courseClasses/{uuid}), enroll people in a class (POST /integrations/courseClasses), remove enrollments (DELETE /integrations/courseClasses) and change an enrollment’s status (PUT /integrations/enrollments/{uuid}/state/{state}).
Course versions (write)	Create and update content versions (POST /integrations/courseVersions/create, PUT /integrations/courseVersions/{uuid}) and create a class from a version (POST /integrations/courseVersions).
Groups (write)	Create, update and delete groups, add or remove people, and link or unlink classes (every write call under /integrations/teams).
Roles (write)	Grant and remove roles (POST /integrations/roles and DELETE /integrations/roles/{uuid}), including administrator roles. Grant only to systems you fully trust. Granting any role also requires Staff login.

• Without the permission, the call receives a 403 error (insufficientScope).
• Enrolling someone who does not exist yet, or adding them to a group, also needs Users (write).
• User authentication (POST /integrations/auth/authenticationRequest) only needs Classes (write) when the call uses autoEnroll with a class, since that is when it enrolls someone. Without autoEnroll, it needs no write permission.
• In classes with enrollment management, changing an enrollment’s status needs Classes (write) and also Enrollments (write).
• Tokens that already made these calls keep working after the platform update. Any other token needs an administrator to check the permission in Edit permissions.

Staff login

The Staff login permission protects management accounts. Without it, the token cannot act on anyone who holds an administrator, publisher, observer or tutor role (division administrators included). It is needed for:

• partner login (POST /integrations/auth/authenticationRequest) of a person with one of these roles;
• granting any role through the API (POST /integrations/roles);
• changing the email or setting the password of a person with one of these roles (PUT /integrations/users/{uuid}).

Participants do not need it. Eduvem platform administrators are always refused, with or without the permission. Without it, the call gets the 403 error (insufficientScope).

• Tokens that existed at the platform upgrade received the permission automatically. New tokens start without it: an institution administrator checks it in Edit permissions.
• When you check it, the screen shows this warning: “Warning: allows this token to sign people in as your administrators, publishers, observers and tutors through partner login, without their password. Turn it on only for a single sign-on integration you fully trust.” The add confirmation repeats the alert: “Warning: with Staff login, this integration can open sessions as your administrators, publishers, observers and tutors without their password.”

Partner login access link

Partner login (POST /integrations/auth/authenticationRequest) returns a URL that your system opens to bring the person into the platform, already signed in and, when a class is given, straight into that class.

• The URL carries a single-use code valid for 2 minutes. It is not the person’s session: the session is created only when the page opens and exchanges the code. After that, the address shown in the browser holds nothing sensitive.
• Generate the URL at the moment of the click and open it right away. Do not store the URL for reuse or send it by e-mail: a link opened a second time, or after 2 minutes, does not sign in.
• In that case the login screen shows: “This access link has expired or was already used. Go back to the system you came from and open the content again.” Going back to the source system and clicking again is enough.
• If another person is already signed in on the same browser, the link switches the session to the link’s person, as before.

Managed enrollments through the API

The Enrollments (write) permission lets the token manage approver delegations and approve, deny and cancel enrollments of classes with enrollment management. It only appears in the permissions list while the institution has enrollment management active (or when the token already holds it), is never ticked by default, and is not included in the Platform permission.

The People sync permission lets the token send the complete list of employees, check syncs, and approve or cancel the syncs sent through the API - see People sync. It only appears in the permissions list while people sync is on for the institution (or when the token already holds it), is never ticked by default, and is not included in the Platform permission. Syncs that trip a safety limit still need a person’s approval on the platform.

Approve, deny and cancel an enrollment

Use the enrollment state endpoint, with the identifier of whoever decides. The token needs Classes (write) and also Enrollments (write):

PUT /integrations/enrollments/{enrollmentUUID}/state/{state}?approverIdentifier=<username, e-mail or CPF>

In a class with enrollment management:

• enrolled approves a requested enrollment; denied denies it. A full class sends the approved person to the waiting list instead of giving the seat.
• cancelled cancels an enrollment that is already enrolled. Any other state change is refused with invalidEnrollmentStateTransition (400).
• approverIdentifier is required and must be a person who could decide that request: the participant’s manager, a substitute of theirs, the manager’s manager (through escalation) or a class administrator. Nobody approves their own request.
• A denial made through the API records the reason Other; there is no reason field.
• On success the response is 204, with no body.
• In classes without enrollment management, the endpoint works as before and ignores approverIdentifier.

The most common errors:

Code	Error	When
403	insufficientScope	The token does not have Enrollments (write) or Classes (write).
403	approverNotAuthorized	The person given cannot decide this request.
400	approverIdentifierRequired, approverNotFound	The approverIdentifier is missing or the person does not exist in the institution.
404	enrollmentNotFound	The enrollment does not exist.
409	requestsClosed	The class deadline passed; the enrollment is closed.
409	enrollmentStateChangedConcurrently	Someone changed the enrollment first.
409	selfApprovalNotAllowed	The approver is the requester.

Waiting-list position

Enrollment reads (GET /integrations/enrollments/{enrollmentUUID} and the listing) carry the enrollmentQueuePosition field: a whole number, where 1 is the next to be enrolled. It is only filled while the enrollment is on the waiting list of a managed class; otherwise it is empty.

Manager substitutes

HR systems can register who substitutes for a manager during a period:

• POST /integrations/managerDelegates, with principalIdentifier (the manager), delegateIdentifier (the substitute), validFrom and validUntil in ISO-8601 format with a time zone (for example, 2026-10-07T12:00:00Z). People are identified by username, e-mail or CPF. It answers 201 with the delegation created, with source equal to integration.
• GET /integrations/managerDelegates?principalIdentifier=<manager> lists only the delegations created by the integration.
• DELETE /integrations/managerDelegates/{delegationUUID} revokes a delegation (204, even if it was already revoked).

The period must start before it ends, end in the future, and last at most 366 days; the substitute must be an active person, different from the manager. These calls answer 403 (insufficientScope) without the permission, or (enrollmentManagementDisabled) if the reporting line or enrollment management is off for the institution, and are limited to 60 calls per minute.

Auditing

Every call made through the API is logged by the platform (what, when and with which token). That log is not shown in the admin panel: if you need to know what an external system did, ask Eduvem support for the lookup, giving the token and the period.

Usage limits

• Traffic is limited per institution (default budget of 1,000 requests per minute, adjustable on request).
• Heavy operations (audit/report exports and certificate downloads) have their own, smaller budget - a spike in those doesn’t block the rest of the integration.
• Listings are paginated (default 100 items per page, maximum 1,000): tell your integrators to always paginate.
• The certificates listing has a lower limit: at most 100 items per page (a larger page is refused).
• Each server accepts at most 2 simultaneous calls per token and 4 per institution. A call beyond that gets error 429 (integrationConcurrencyExceeded) with the header Retry-After: 5: wait and retry. Integrations that make one call at a time are never affected.
• To keep an external system in sync, don’t download every enrollment on each run: after the first load, send lastModified with the time the previous sync started and update records by enrollment identifier. Stop paging when a page returns fewer items than the page size you asked for.
• In the page-number enrollments listing, the totals (count and pageCount) are computed once per filter combination on each server and reused for up to 10 minutes: they can lag enrollments created or changed in that window. That is why the stop condition is a short page, not pageCount.
• A query too heavy to finish within the database time limit gets error 503 (queryTimeout) with the header Retry-After: 60: wait a minute and retry, preferably with narrower filters or with the cursor paging described in the API documentation.

Tip

Treat tokens like passwords: never in spreadsheets or emails, always one per system, and revoke tokens for deactivated integrations right away.

See also

• API documentation