Public API authentication: keys, scopes and security

Studeia's public API exposes the /api/institution/* routes for integrations. Every request is authenticated by session (in the app) or by API key (Bearer). This guide covers keys, scopes and best practices.

Quick answer

Authenticate with a Bearer token (key with mia_ prefix)
Keys are created in Settings → API Keys
Scopes in the resource:action pattern limit each key
The full key appears only once (server stores only the hash)
Sensitive operations accept session only, never an API key

How to authenticate

Send the key in the Authorization header:

GET /api/institution/courses
Authorization: Bearer mia_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Dual auth (resolveAuth) accepts session (in the app) or API key (integrations). For keys, the response includes rate-limit headers.

Scopes (least privilege)

Scopes follow the resource:action pattern. Examples:

Resource	Read	Write
Courses	`courses:read`	`courses:write`
Users	`users:read`	`users:write`
Enrollments	`enrollments:read`	`enrollments:write`
Classes	`classes:read`	`classes:write`
Reports	`reports:read`	—

Create keys with the minimum scopes needed. A key used only to read reports doesn't need write scopes.

Key security

The full key is shown only once at creation.
The server stores only the SHA-256 hash — the key isn't recoverable.
Revoking/editing a key invalidates access immediately.
On leak, revoke and generate a new one.

Routes that do NOT accept an API key

For security, critical operations require session authentication (sessionOnly) and never accept an API key:

API key management.
Billing / checkout (avoids automating purchases).
AI supervisor moderation.

Best practices

Use least privilege for scopes.
Rotate keys periodically.
Never expose the key in the frontend or in repositories.
Monitor usage (every request is logged).
Handle rate limits (see the dedicated page).

FAQ

How do I authenticate? Bearer token with the mia_ key in the Authorization header.

What are scopes? resource:action limits on what the key can do.

Is the key visible afterward? No — only at creation; the server stores only the hash.

Does it work for any route? For most; billing, keys and moderation are session-only.

See the API overview and webhooks and rate limits.

FAQ

How do I authenticate a request to Studeia's API?

Send the API key in the Authorization header as a Bearer token. Keys have the mia_ prefix and are generated in the institution's Settings → API Keys. Each request also goes through rate limiting, and usage is logged for auditing.

What are scopes and why do they matter?

Scopes limit what each key can do, in the resource:action pattern (e.g., courses:read, users:write). A key only performs operations covered by its scopes. Create keys with the minimum scopes needed (least privilege) — a read key shouldn't have write scopes.

Is the full API key visible after creation?

No. The full key is shown only once, at creation. The server stores only a hash (SHA-256), so the key can't be retrieved later. Store it securely; if lost, revoke it and generate a new one.

Can I use the API key for any institutional route?

For most /api/institution/* routes, yes — with the right scope. Exceptions: sensitive operations (API key management, billing/checkout, AI supervisor moderation) accept session authentication only (sessionOnly), never an API key, to avoid automating critical actions.