IntelliPlan Developer API Keys and Scopes

Third-party apps that need access to a student’s IntelliPlan data—assignments, grades, schedule, streak, and profile—authenticate with a scoped, revocable API key rather than a session token. This separation is intentional: a session token (Authorization: Bearer …) carries every scope and cannot be revoked without rotating the entire signing secret, making it unsuitable for anything outside IntelliPlan’s own first-party clients (the MCP server, the browser extension). An API key (X-API-Key: ip_live_…) is scoped to exactly what you asked for, rate-limited per key, and can be revoked instantly without touching any other credential.

Applying for a Key

Visit intelliplan.tech/developers while signed in to your IntelliPlan account. The application form asks for four things:

App Name and URL

A short, human-readable name (2–120 characters) for your integration and an optional URL where it lives. These appear in the approval email and in the developer dashboard.

Use Case Description

At least 40 characters describing what you are building and how it uses student data. This is the text a reviewer reads for write-scope applications — be specific.

Scopes

Pick one or more scopes from the scopes table below. Only scopes with write: false are eligible for auto-approval. Any write scope sends the application to human review.

Expected Volume

Declare your anticipated request rate: low, medium, or high. This sets your per-minute rate limit ceiling (see Rate Limits).

Your IntelliPlan account must be at least one hour old before an auto-approval can be granted. This prevents a throwaway signup from receiving a live credential in the same minute it was created. The restriction does not apply to human-reviewed applications.

You may hold up to 5 open applications or active keys at a time. Revoke an existing key before applying again if you have reached that limit.

Approval Flow

Read-Only (Auto-Approved)
Write Scopes (Human Review)

Applications that request only read-only scopes from an account at least one hour old are approved automatically. The API key is returned in the POST /developers/apply response body and also sent to your contact email.

201 Auto-Approved Response

{
  "status": "approved",
  "message": "Approved. Copy the key now — this is the only time we show it.",
  "key": "ip_live_AbCdEfGhIjKlMnOpQrStUvWxYz012345678901234567",
  "application": {
    "id": 42,
    "app_name": "Study Tracker",
    "scopes": "read:assignments read:streak",
    "status": "active",
    "rate_limit_per_min": 60
  }
}

Any application that includes at least one write:* scope is sent to the IntelliPlan review queue. A team member will respond within two business days and email you either way. Auto-approved rate limits start at 60 req/min; an admin can raise this for write-approved keys.

202 Pending Response

{
  "status": "pending",
  "message": "Submitted. Write access is reviewed by a person, usually within two business days. We'll email you either way.",
  "application": {
    "id": 43,
    "app_name": "Study Bot",
    "scopes": "read:assignments write:tasks",
    "status": "pending"
  }
}

Copy your key immediately. IntelliPlan stores only the SHA-256 hash of the secret — the plaintext is shown exactly once, at the moment of approval. If you lose the key, you must roll it (see Rolling a Lost Key).

Key Format

Every API key begins with the prefix ip_live_ followed by 43 characters of URL-safe random entropy generated by Python’s secrets.token_urlsafe(32). The full key looks like:

ip_live_AbCdEfGhIjKlMnOpQrStUvWxYz012345678901234567

Only the first ip_live_ + 6 characters are stored as a display prefix so you can identify a key in the dashboard without exposing the secret. The full secret is stored only as a SHA-256 hex digest. An incorrect key produces a lookup miss rather than a timing-sensitive comparison.

Using Your Key in Requests

Pass the key in the X-API-Key request header on every call to /api/v1/:

Example: List Assignments

curl https://intelliplan.tech/api/v1/assignments \
  -H "X-API-Key: ip_live_AbCdEfGhIjKlMnOpQrStUvWxYz012345678901234567"

Python (requests)

import requests

API_KEY = "ip_live_AbCdEfGhIjKlMnOpQrStUvWxYz012345678901234567"

resp = requests.get(
    "https://intelliplan.tech/api/v1/assignments",
    headers={"X-API-Key": API_KEY},
)
resp.raise_for_status()
print(resp.json())

TypeScript (fetch)

const API_KEY = "ip_live_AbCdEfGhIjKlMnOpQrStUvWxYz012345678901234567";

const response = await fetch("https://intelliplan.tech/api/v1/assignments", {
  headers: { "X-API-Key": API_KEY },
});
const data = await response.json();

Only the X-API-Key header is supported for third-party API keys. The Authorization: Bearer … header is reserved for IntelliPlan’s own first-party clients (MCP server, browser extension) that authenticate directly with a user’s credentials. Bearer tokens carry every scope and cannot be revoked individually.

API Key vs Bearer Token

Property	`X-API-Key`	`Authorization: Bearer`
Who uses it	Third-party developers	IntelliPlan first-party clients
Scopes	Exactly what you applied for	All scopes
Revocable	Yes, instantly	Only by rotating `SECRET_KEY`
Rate-limited per credential	Yes	No
Shown once / stored as hash	Yes	No
Intended for public distribution	Yes	No

Available Scopes

Every scope you can request is listed in the table below. The write column determines whether an application goes to human review.

Scope	Label	Description	Requires Review
`read:profile`	Read profile	Name, email, and account creation date.	No
`read:assignments`	Read assignments	The unified assignment list from every connected source.	No
`read:tests`	Read tests	Assignments the student has marked as tests.	No
`read:schedule`	Read schedule	Saved study plans and their progress.	No
`read:streak`	Read streak	Sparks, streak length, level, and quest state.	No
`read:grades`	Read grades	Course grades and GPA from the connected school platform.	No
`read:identity`	Read learning profile	Grade level, focus areas, goals, availability.	No
`write:tasks`	Create tasks	Add manual tasks, dismiss and restore assignments.	Yes
`write:tests`	Mark tests	Mark and unmark assignments as tests.	Yes
`write:schedule`	Generate schedules	Run the scheduler and save the resulting plan.	Yes
`write:identity`	Update learning profile	Change grade level, focus areas, goals, availability.	Yes

read:grades is intentionally separate from read:assignments. An app that only needs to show what is due does not need to know what a student scored. Request only the scopes you actually use — narrower scope applications clear review faster.

You can also fetch the live scope list programmatically:

GET /developers/scopes

curl https://intelliplan.tech/developers/scopes

The response includes auto_approved (the list of read-only scope names), max_keys_per_user (5), and volume_limits (low: 60, medium: 300, high: 1000).

Rate Limits

Rate limits are enforced per API key, not per IP address. The ceiling is set at application time based on expected_volume:

Declared Volume	Requests per Minute
`low`	60
`medium`	300
`high`	1,000

Auto-approved (read-only) keys always start at the low limit of 60 req/min regardless of declared volume. An admin can raise the limit for write-approved keys at review time. expected_volume is self-reported — declaring high with write scopes does not bypass review.

Every approved key tracks last_used_at and a cumulative request_count. If you are rate-limited you will receive a 429 Too Many Requests response.

Rolling a Lost Key

If your key is lost or compromised, roll it immediately. Rolling replaces the secret atomically — the old key stops working the instant the roll succeeds. There is no grace period.

POST /developers/keys/{key_id}/roll

curl -X POST https://intelliplan.tech/developers/keys/42/roll \
  -H "Cookie: session=<your-session-cookie>"

Roll Response

{
  "status": "ok",
  "message": "Rolled. The previous key stopped working just now.",
  "key": "ip_live_NewSecretHere...",
  "application": {
    "id": 42,
    "status": "active"
  }
}

Rolling requires an active browser session (login_required). You cannot roll a key that is in pending or revoked status — only active keys can be rolled.

Revoking a Key

To permanently deactivate a key, call the revoke endpoint. Revoked keys cannot be re-activated; you would need to apply for a new key.

POST /developers/keys/{key_id}/revoke

curl -X POST https://intelliplan.tech/developers/keys/42/revoke \
  -H "Cookie: session=<your-session-cookie>"

Revocation clears the stored key hash immediately so the credential can never match again, even if the plaintext surfaced later.

Viewing Your Applications

GET /developers/applications

curl https://intelliplan.tech/developers/applications \
  -H "Cookie: session=<your-session-cookie>"

The response includes all your applications ordered by creation date, plus slots_remaining (how many more keys you can apply for before hitting the 5-key limit).

Application Status Values

Status	Meaning
`pending`	Submitted, waiting for review (write scopes) or waiting for auto-approval logic (should resolve instantly for read-only).
`active`	Approved; the key is live and can authenticate API requests.
`denied`	A reviewer declined the application. The denial note (if provided) is in `review_note`.
`revoked`	You or an admin revoked the key. The hash has been cleared.

Overview

Endpoints

Developer Tools

IntelliPlan Developer API Keys and Scopes

Applying for a Key

Approval Flow

Key Format

Using Your Key in Requests

API Key vs Bearer Token

Available Scopes

Rate Limits

Rolling a Lost Key

Revoking a Key

Viewing Your Applications

Build docs developers (and LLMs) love

Overview

Endpoints

Developer Tools

Documentation Index

​Applying for a Key

​Approval Flow

​Key Format

​Using Your Key in Requests

​API Key vs Bearer Token

​Available Scopes

​Rate Limits

​Rolling a Lost Key

​Revoking a Key

​Viewing Your Applications

Build docs developers (and LLMs) love

Applying for a Key

Approval Flow

Key Format

Using Your Key in Requests

API Key vs Bearer Token

Available Scopes

Rate Limits

Rolling a Lost Key

Revoking a Key

Viewing Your Applications