Every IntelliPlan API request must prove its identity before touching student data. The API supports two authentication schemes — API keys for third-party integrations and Bearer tokens for first-party clients — and they serve different trust boundaries by design. API keys are scoped, revocable, and rate-limited per key, so a compromised credential can be neutralised instantly without affecting other integrations. Bearer tokens carry every scope and are tied to the server’s secret key, so they are reserved for software the student runs on their own behalf. Choosing the right scheme up front keeps your integration secure and your key’s blast radius small.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/UAnirudh/IntelliPlan/llms.txt
Use this file to discover all available pages before exploring further.
Choosing an Authentication Method
- API Key (X-API-Key)
- Bearer Token
Use an API key when you are building a third-party application that accesses IntelliPlan data on behalf of a student who has authorised your app. This is the scheme the documentation describes and the one you should use by default.Characteristics:
- Prefixed with
ip_live_— easy to detect in logs and.envfiles - Scoped to exactly the permissions you requested at application time
- Revocable immediately from the developer dashboard; the old key stops working the instant it is rolled or revoked
- Rate-limited per key (not per IP), so your integration has its own budget
- Stored as a SHA-256 hash on IntelliPlan’s servers — the plaintext is never recoverable after issuance
API Key example
If the API receives both an
X-API-Key header and an Authorization: Bearer header on the same request, the API key takes precedence. The narrower, revocable credential always governs. Additionally, if you accidentally paste an ip_live_… key into the Authorization: Bearer field, the API detects it and accepts it rather than returning a 401.API Key Authentication
How to Apply
Navigate to intelliplan.tech/developers while signed in to your IntelliPlan account. You cannot obtain a key without a registered account, and your account must be at least one hour old before applications are accepted.Fill out the application form
Provide:
- App name — what your integration is called (2–120 characters)
- App URL — a link to your project or documentation (optional but recommended)
- Use case — describe what you are building in at least 40 characters; this is the primary thing a reviewer reads for write-scope applications
- Contact email — defaults to your account email; used to deliver your key and any review decisions
- Expected volume —
low,medium, orhigh(see rate limits below)
Select scopes
Choose the minimum set of scopes your integration actually needs. The scope selector at
/developers/scopes lists every available scope with labels, descriptions, and whether human review is required.Receive your key
- Read-only applications are approved automatically and the key is returned in the same response.
- Write-scope applications are queued for human review, typically within two business days. You will receive an email either way.
Using Your API Key
Send the key in theX-API-Key request header on every call:
Authenticated request with an API key
ip_live_. If your key does not match this prefix, it will not be recognised.
Rolling a Lost Key
If you lose your key or suspect it has been compromised, roll it from the developer dashboard. The previous key stops working the instant the roll completes — there is no grace period.Roll a key via the developer API (authenticated web session)
Rate Limits
Your key’s rate-limit ceiling is set when the application is approved and is based on theexpected_volume you declared:
| Volume tier | Requests per minute |
|---|---|
low | 60 |
medium | 300 |
high | 1,000 |
X-RateLimit-Limit header on every API response shows the ceiling for the current key. When you exceed it, you receive a 429 rate_limited error with an optional retry_after field. The high tier requires human approval regardless of scope type.
Bearer Token Authentication
Bearer tokens are for first-party clients only — software the student runs directly. Do not use Bearer tokens in third-party integrations.Obtaining a Token
POST /api/v1/auth/token does not require any prior credential. Send a JSON body with email and password:
Exchange credentials for a Bearer token
Successful response
The Bearer token to include in subsequent
Authorization: Bearer … headers. This is a signed, time-limited token produced by itsdangerous.URLSafeTimedSerializer — it is not a JWT. The token is opaque; do not attempt to decode or inspect its payload. Its default lifetime is 30 days (configurable via the INTELLIPLAN_TOKEN_AGE environment variable). After expiry, verify_token returns None and the request is rejected with a 401 unauthorized error.Always
"Bearer".All available scopes — Bearer tokens carry every scope with no restrictions.
Basic account info:
id, email, and name.Using the Token
Include the token in theAuthorization header as a standard Bearer credential:
Authenticated request with a Bearer token
JavaScript / fetch
Python / requests
Scopes Reference
Scopes define exactly what a credential is allowed to do. API keys are restricted to the scopes selected at application time. Bearer tokens carry all scopes automatically. Each scope is either read-only (auto-approvable for API keys) or a write scope (requires human review).| Scope | Label | Requires Review | Description |
|---|---|---|---|
read:profile | Read profile | ✗ | Name, email, and account creation date. |
read:assignments | Read assignments | ✗ | The unified assignment list from every connected source. |
read:tests | Read tests | ✗ | Assignments the student has marked as tests. |
read:schedule | Read schedule | ✗ | Saved study plans and their progress. |
read:streak | Read streak | ✗ | Sparks, streak length, level, and quest state. |
read:grades | Read grades | ✗ | Course grades and GPA from the connected school platform. |
read:identity | Read learning profile | ✗ | Grade level, focus areas, goals, availability. |
write:tasks | Create tasks | ✔ | Add manual tasks, dismiss and restore assignments. |
write:tests | Mark tests | ✔ | Mark and unmark assignments as tests. |
write:schedule | Generate schedules | ✔ | Run the scheduler and save the resulting plan. |
write:identity | Update learning profile | ✔ | Change grade level, focus areas, goals, availability. |
read:grades is intentionally separate from read:assignments. Knowing what a student has due is a different level of trust from knowing what they scored. Request only what your integration genuinely needs.Why are write scopes reviewed by a human?
Why are write scopes reviewed by a human?
Write scopes allow your application to create tasks, dismiss assignments, generate study schedules, or alter a student’s learning profile. These actions modify a student’s account directly. IntelliPlan reviews write-scope applications to verify the use case is legitimate and the scope selection is proportionate to what is being built. Review typically takes under two business days.
Authentication Errors
When a request fails authentication or authorisation, you receive one of these error envelopes:- Missing credential (401)
- Invalid key or token (401)
- Missing scope (403)
X-API-Key header and no Authorization header were sent, or the values were empty.Security Best Practices
Store keys in environment variables
Never hardcode
ip_live_… keys in source code or commit them to version control. Use .env files locally and secret management (Railway variables, GitHub Secrets, etc.) in production.Request minimum scopes
Only request the scopes your integration actually uses. A read-only dashboard widget does not need
write:tasks. Narrow scope means a smaller blast radius if the key is ever exposed.Roll compromised keys immediately
If a key is accidentally committed or leaked, roll it from the developer dashboard without delay. The old key is invalidated the instant the roll completes — no grace period, no overlap window.
Use API keys for third-party apps
Never distribute a Bearer token to end users or embed one in a third-party app. Bearer tokens carry all scopes and cannot be revoked per-client. API keys are the correct credential for anything you ship to others.
Complete Code Examples
- cURL (API Key)
- Python (API Key)
- Python (Bearer Token)
- JavaScript (API Key)
List assignments with an API key
Create a manual task
Next Steps
API Overview
Review the base URL, error envelope, response headers, and a map of every endpoint group.
Apply for an API Key
Submit your application, select scopes, and receive your
ip_live_… key at the developer portal.