TribePeer Institutions API

Server-to-server JWT API for approved Tribe Owners. Keep Client Secrets on your backend only.

1. Get credentials

Apply as a Tribe Owner inside TribePeer. After approval you receive a Client ID and Client Secret. Admins can activate or deactivate keys anytime.

2. Exchange credentials for a JWT

POST /api/partner/v1/auth/token
Content-Type: application/json

{
  "client_id": "tp_id_...",
  "client_secret": "tp_sec_..."
}

→ {
  "access_token": "<jwt>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "expires_at": "2026-07-16T..."
}

Inactive keys and inactive institutions are rejected even if the secret is correct.

3. Call authenticated endpoints

Authorization: Bearer <access_token>

4. Endpoints

• GET /api/partner/v1/me — institution + key metadata
• GET /api/partner/v1/tribes — tribes owned by the institution owner
• POST /api/partner/v1/join-codes — create a learner join code
• POST /api/partner/v1/enrollments — enroll by email + join code
• GET /api/partner/v1/results — quiz results (optional tribe_uuid, email, limit)

Create join code

POST /api/partner/v1/join-codes
{
  "tribe_uuid": "...",
  "label": "SS2 Science 2026",
  "max_uses": 120,
  "expires_at": "2026-12-31T23:59:59Z"
}

→ { "join_code": { "code": "ABCD1234", "join_url": "https://.../join/ABCD1234", ... } }

Enroll learner

POST /api/partner/v1/enrollments
{
  "email": "student@school.edu",
  "join_code": "ABCD1234"
}

→ 200 enrolled | 202 pending_registration (share join_url)

If the email already has a TribePeer account, they are enrolled immediately. Otherwise the response includes a join_url learners can open after registering.

Learner redeem

Signed-in learners can open /join/{code} to join the tribe linked to that code.

Security

• Never put secrets in browser / mobile apps — server-to-server only.
• Inactive keys are rejected even if the secret is correct.
• Rotate keys from admin if compromised.
• Partner requests are logged for ops visibility.