Embed & integration guide

Overview

Embed-first: iframe URLs for interviews, reports, and dashboards. Mint students and invites from your backend, then open short-lived embed tokens in the browser.

• API key never leaves your server
• Embed JWTs are purpose-scoped and short-lived
• Webhooks notify you when sessions complete
• Rate limit: 100 requests / minute per partner

Two-token architecture

1) Your backend calls Partner APIs with `X-Partner-API-Key`. 2) You receive an embed JWT. 3) The browser loads an iframe with that JWT — never the API key.

Your LMS/HR backend
  → POST /students + POST /embed-token  (API key)
  ← embed JWT
Browser iframe
  → /embed?token=…  (JWT only)

Authentication & conventions

All server-to-server calls require these headers:

X-Partner-API-Key: <your_api_key>
Content-Type: application/json
Accept: application/json

Responses use the standard envelope: { "status": "success"|"error", "data": ..., "message": "..." }.

Flow: Institute student SSO

1. Create or upsert the student (POST /students)
2. Mint an embed token (POST /embed-token)
3. Open the iframe with the token

curl -X POST https://www.vriona.com/api/v1/partner/students \
  -H "X-Partner-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_student_id":"stu_123","email":"a@college.edu","name":"Ada"}'

curl -X POST https://www.vriona.com/api/v1/partner/embed-token \
  -H "X-Partner-API-Key: $KEY" \
  -d '{"purpose":"dashboard","external_student_id":"stu_123"}'

Flow: HR interview invite

Create an invite from your HR system, optionally email the candidate, then open the interview iframe with a one-time `purpose: interview` token.

Flow: HR dashboard SSO

Mint `purpose: hr_dashboard` (8h TTL) to embed the HR dashboard without a separate Vriona login.

POST /api/v1/partner/embed-token
{ "purpose": "hr_dashboard", "external_hr_id": "hr_42" }

Invite endpoints

• POST /invites — create invite
• POST /invites/bulk — batch create
• GET /invites — list
• GET /invites/{id} — detail
• DELETE /invites/{id} — revoke

Student endpoints

• POST /students — upsert student
• POST /students/bulk — batch upsert
• GET /students/{id}/history — interview history

Embedding in your site

Interview iframe example:

<iframe
  src="https://www.vriona.com/embed/interview?token=EMBED_JWT"
  allow="camera; microphone; display-capture"
  style="width:100%;height:80vh;border:0"
></iframe>

Also supported: student dashboard and report embeds with matching token purposes.

Embed token purposes

Webhooks

Subscribe to session lifecycle events. Signatures use HMAC-SHA256 over the raw body (`X-Vriona-Signature`).

• interview.started / interview.completed
• coding.started / coding.completed
• invite.accepted / invite.expired
• report.ready / student.updated

Failed deliveries retry with backoff. Always verify the signature before trusting the payload.

Analytics & leaderboard

• GET /analytics — aggregate partner metrics
• GET /leaderboard — ranked student performance

Placement pool

• PATCH /placement/opt-in — student consent
• GET /placement/eligible — searchable candidates
• GET /placement/active — active pool
• POST /placement/promote — promote to HR shortlist

Troubleshooting

Local testing

Use the partner integration test HTML from the repo with a local static server:

python3 -m http.server 8081

Point the page at your partner API key and base URL to exercise SSO and embed flows end-to-end.