Skip to main content

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.

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.

Choosing an Authentication Method

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 .env files
  • 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
curl https://intelliplan.tech/api/v1/me \
  -H "X-API-Key: ip_live_YOUR_KEY_HERE"
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.
1

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, or high (see rate limits below)
2

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.
3

Accept the API terms

You must check the acceptance box before submitting.
4

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.
Copy your key the moment it appears. This is the only time it is shown in plaintext. IntelliPlan stores only a SHA-256 hash and cannot recover your key.
Each account may hold up to 5 active or pending keys. Revoke unused keys before applying for new ones — pending applications count against this limit.

Using Your API Key

Send the key in the X-API-Key request header on every call:
Authenticated request with an API key
curl https://intelliplan.tech/api/v1/assignments \
  -H "X-API-Key: ip_live_YOUR_KEY_HERE"
Keys always start with 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)
POST /developers/keys/{key_id}/roll
The response contains the new plaintext secret, shown exactly once. Store it immediately.

Rate Limits

Your key’s rate-limit ceiling is set when the application is approved and is based on the expected_volume you declared:
Volume tierRequests per minute
low60
medium300
high1,000
The 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
curl -X POST https://intelliplan.tech/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email": "student@university.edu", "password": "correct-horse-battery"}'
Successful response
{
  "token": "InsiZW1haWwiOiAic3R1ZGVudEB1bml2ZXJzaXR5LmVkdSIsICJ1c2VyX2lkIjogNDJ9.YOUR_SIGNATURE",
  "token_type": "Bearer",
  "scopes": [
    "read:profile", "read:assignments", "read:tests",
    "read:schedule", "read:streak", "read:grades",
    "read:identity", "write:tasks", "write:tests",
    "write:schedule", "write:identity"
  ],
  "user": {
    "id": 42,
    "email": "student@university.edu",
    "name": "Alex Chen"
  }
}
token
string
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.
token_type
string
Always "Bearer".
scopes
array
All available scopes — Bearer tokens carry every scope with no restrictions.
user
object
Basic account info: id, email, and name.

Using the Token

Include the token in the Authorization header as a standard Bearer credential:
Authenticated request with a Bearer token
curl https://intelliplan.tech/api/v1/me \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"
JavaScript / fetch
const response = await fetch("https://intelliplan.tech/api/v1/assignments", {
  headers: {
    "Authorization": `Bearer ${token}`,
    "Content-Type": "application/json",
  },
});
const data = await response.json();
Python / requests
import requests

resp = requests.get(
    "https://intelliplan.tech/api/v1/assignments",
    headers={"Authorization": f"Bearer {token}"},
)
data = resp.json()

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).
ScopeLabelRequires ReviewDescription
read:profileRead profile✗Name, email, and account creation date.
read:assignmentsRead assignments✗The unified assignment list from every connected source.
read:testsRead tests✗Assignments the student has marked as tests.
read:scheduleRead schedule✗Saved study plans and their progress.
read:streakRead streak✗Sparks, streak length, level, and quest state.
read:gradesRead grades✗Course grades and GPA from the connected school platform.
read:identityRead learning profile✗Grade level, focus areas, goals, availability.
write:tasksCreate tasks✔Add manual tasks, dismiss and restore assignments.
write:testsMark tests✔Mark and unmark assignments as tests.
write:scheduleGenerate schedules✔Run the scheduler and save the resulting plan.
write:identityUpdate 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.
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:
{
  "status": "error",
  "error": "unauthorized",
  "message": "Send a valid `X-API-Key` header, or a Bearer token from POST /api/v1/auth/token. Apply for a key at /developers.",
  "request_id": "a1b2c3d4e5f60718"
}
Cause: No 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

List assignments with an API key
curl https://intelliplan.tech/api/v1/assignments \
  -H "X-API-Key: ip_live_YOUR_KEY_HERE"
Create a manual task
curl -X POST https://intelliplan.tech/api/v1/tasks \
  -H "X-API-Key: ip_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Review chapter 5 notes",
    "due_date": "2025-01-20",
    "priority": "High",
    "course": "Biology",
    "estimated_time": 90
  }'

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.

Build docs developers (and LLMs) love