API access & tokens
Create, scope and revoke API tokens, authenticate requests, and use the API to sync students, enrolments and progress with your own systems.
API tokens let your own software — a student information system, an admissions portal, a reporting script — work with your ValidBridge organization without a person signing in. Each token belongs to one organization.
Who can use it
Create a token
- In the dashboard, open Developers → API Access (open API Access).
- On the API Tokens tab, click Create Token.
- Give it a Token Name that says what uses it (for example “SIS nightly sync”) and, optionally, a description.
- Optionally set an Expiration Date. Leave it empty for a token that never expires.
- Choose its Permissions (see below) and create it.
- Copy the token straight away and store it in your password manager or secrets store. It is shown only once. Tokens start with
vb_.
Permissions
- Read Only
- — the token can read but not change anything. The safe default.
- Full Access
- — create, read, update and delete on every resource.
- Custom
- — tick create, read, update or delete per resource: courses, activities, assignments, chapters, folders, media, certifications, user groups and payments, plus search.
Give each integration its own token with the narrowest permissions it needs, so you can revoke one without breaking the others.
Authenticate requests
Send the token in the Authorization header of every request, as a bearer token:
Authorization: Bearer vb_your_token_hereRequests and responses are JSON. The Documentation & Playground tab on the same page lists every endpoint with its full address, parameters and example responses, lets you try calls with your token, and gives you a ready-to-copy curl command.
What you can do with it
The school-administration part of the API is built for syncing with your own systems. All of it is scoped to your organization's slug (the name in your ValidBridge address). The most useful calls:
| Task | Request |
|---|---|
| Create (provision) a student or staff account | POST /admin/{org_slug}/users |
| Find a user by email | GET /admin/{org_slug}/users/by-email/{email} |
| Enrol a user in a course | POST /admin/{org_slug}/enrollments/{user_id}/{course_uuid} |
| Enrol many users at once | POST /admin/{org_slug}/enrollments/bulk |
| Read a user’s progress in all courses | GET /admin/{org_slug}/progress/{user_id} |
| List a user’s certificates | GET /admin/{org_slug}/certifications/{user_id} |
| Add a user to a user group (class, stream) | POST /admin/{org_slug}/usergroups/{usergroup_uuid}/members/{user_id} |
| Send a user a one-click sign-in link from your portal | POST /admin/{org_slug}/auth/magic-link |
Paths are relative to the API address shown in the playground. The playground is the reference: it is always up to date with what your plan allows.
Admin and staff accounts are protected
Limits
- Creating or regenerating tokens: 10 per hour.
- Provisioning users: 30 per minute per token.
- Looking users up by email: 60 per minute per token.
Over a limit, the API answers 429 Too Many Requests. Wait and retry, and spread large imports out or use the bulk enrolment call.
Revoke or regenerate a token
The token list shows each token's prefix, status, when it was last used and when it expires. From a token's actions:
- Regenerate issues a new secret for the same token and settings. The old secret stops working immediately, so update your integration at once.
- Revoke switches the token off for good. Use it when an integration is retired or a token may have leaked.
Treat tokens like passwords
Was this article helpful?