Get started

Authentication

Your servers authenticate with API keys. Browsers and apps never see a key — they get join links, which GurukulLive turns into a session limited to one meeting.

API keys

Organization owners and admins create keys in Settings → API keys. A key looks like vmk_live_… (production) or vmk_test_… (sandbox organization). GurukulLive stores only a SHA-256 hash and the last four characters, so the full key is shown exactly once.

Send it on every request — preferably as a bearer token:

http

GET /api/v1/public/meetings?status=LIVE HTTP/1.1
Host: gurukullive.example.com
Authorization: Bearer vmk_live_…

# also accepted:
X-API-Key: vmk_live_…

A key acts as your organization, not as a person: it can manage the organization's users, classes and meetings within its scopes. Write operations are written to the audit log with the key's name and the admin who created it.

curl -X GET https://gurukullive.example.com/api/v1/public/meetings?status=LIVE&limit=20 \
  -H "Authorization: Bearer $VMEET_API_KEY"

Scopes

Give each integration only what it needs. A request without the right scope fails with 403 insufficient_scope.

Scope	Grants
`users:read`	List and read users
`users:write`	Create/upsert, update, deactivate, reactivate and remove users; bulk provisioning
`classes:read`	Read classes, courses, batches, teacher assignments and enrollments
`classes:write`	Manage classes, courses, batches, assignments and enrollments
`meetings:read`	List meetings, live/final rosters
`meetings:write`	Create, update, start, end and delete meetings; mint join links (HOST/COHOST links need this scope)
`recordings:read`	List recordings and create playback / embeddable player URLs
`recordings:write`	Delete recordings
`attendance:read`	Attendance per meeting and per class (JSON or CSV)
`webhooks:read`	List webhook endpoints and their delivery logs
`webhooks:write`	Create, update, delete, test and rotate webhook endpoints; redeliver
`analytics:read`	Usage: participant-minutes, recording hours, storage
`*`	Every current and future scope. Only the organization owner can create these.

Expiry, IP allowlists and revocation

Expiry — optional. Expired keys fail with 401 api_key_expired.
IP allowlist — optional list of IPv4/IPv6 addresses or CIDR ranges. Requests from anywhere else fail with 403 ip_not_allowed.
Revocation is immediate: the next request fails with 401 api_key_revoked.
The settings page shows when each key was last used (updated about once a minute).

Rotating a key without downtime

Create a new key with the same scopes.
Deploy it to your servers.
Watch the old key's “last used” stop moving, then revoke it.

Plan access

API access is part of your GurukulLive plan. If the plan does not include it, requests fail with 402 plan_limit_reached. Some plans include read-only access (recordings:read, attendance:read) — other scopes then return 402 as well.

Meeting sessions (browsers and apps)

End users authenticate with a join link, not an API key. Exchanging the link's token at POST /api/v1/join-tokens/exchange returns a short-lived JWT whose scope is a single meeting (meeting:<id>). It works only on that meeting's routes, is refreshable for up to 24 hours with POST /api/v1/join-tokens/refresh, and is revoked when the user is deactivated. GurukulLive's own embed and join-link pages handle all of this for you; native apps that build their own UI use it directly.

Checklist

Keep keys in a secret manager or environment variables — never in source control, browsers or mobile apps.
One key per integration and environment, with the smallest set of scopes.
Add an IP allowlist when your servers have fixed egress addresses.
Log the requestId from error responses; support can trace it.