Authentication
Three ways to talk to the API, depending on who is calling.
Personal access tokens (PAT)
For scripts and server integrations. They go in the Authorization: Bearer edr_live_… header and act with your permissions in a single institution, the one you choose when you create it: in any other, even one you also belong to, the answer is 404. Each token is read or write and always expires (1 to 90 days); underage learners cannot create them.
- They are shown only once when created; EduRails only stores their fingerprint (SHA-256).
- A read-only token that tries to write gets
credential_read_only. - Revoke it as soon as it is no longer needed or if you suspect it has leaked.
- Never put it in a URL or in browser code.
OAuth 2.1 for third-party applications
For applications acting on behalf of other people (an MCP connector, for example): authorization code with PKCE (S256 required). Discovery lives at https://app.edurails.com/.well-known/oauth-authorization-server.
| Scope | What it allows |
|---|---|
edurails | The only scope. When consenting, the person picks ONE institution and whether access is read or write (learners: read only); the rest is decided by their role in that institution. |
The browser session
The EduRails website uses HttpOnly cookies (a 15-minute access_token and a rotating refresh_token). They are not for integrations: do not copy them from a browser into a script.
Rate limits
If you go over the limit, the response is 429 too_many_requests with a Retry-After header (seconds). Wait that long before retrying and use exponential backoff.
The organization goes in the path
The org_id in the path is checked against your memberships on every call: if you do not belong to that organization, 404; if it is suspended, 403 organization_suspended. List yours with GET /api/v1/me/organizations.