Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.hawkings.education/llms.txt

Use this file to discover all available pages before exploring further.

Hawkings uses API keys for all authentication. There are two flavours and they look almost identical — pick the one that fits your case.

​
Key shapes

ShapeLooks likeCarries
Shorthk-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXXA user identity
Longhk-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX-{platform}User + platform
X are hex characters; {platform} is the 24-char workspace identifier.
Use a long key in server code. It encodes both who you are and the workspace you operate on, so you don’t have to carry a separate HAWKINGS_PLATFORM environment variable.

​
Pass the key to the SDK

The SDK reads HAWKINGS_API_KEY and HAWKINGS_PLATFORM from the environment by default. You can also pass them in code: 
import Hawkings from "@hawkings/sdk";

// Long key — no extra config needed
const hk = new Hawkings({ api_key: "hk-...-...-...-...-...-{platform}" });

// Short key — pass platform separately
const hk = new Hawkings({
  api_key: "hk-...-...-...-...-...",
  platform: "abc123def456ghi789jkl012",
});

​
Scopes

Every key has one or more scopes. The default key issued in the dashboard carries read:* and write:* for everything in its workspace. For machine-to-machine integrations create scoped keys:
ScopeWhat it allows
read:coursesList, retrieve, expand Course, Cohort, Unit, Lesson.
write:coursesAbove + create / update / delete authoring resources.
read:studentsList students and their progress.
write:submissionsCreate submissions (use this for student-facing apps).
ai:generateRun *.generate*() calls.
ai:gradeRun submissions.gradeWithAi().
The dashboard generates scoped keys via copy-paste; programmatically you’d use the Auth API.

​
End-user authentication

If you’re building a student-facing product, you don’t want to ship your platform-wide key to a browser. Use the token flow: 
// Server-side: ask Hawkings for a one-time token for this user
const { token } = await hk.auth.tokenStart({ email: student.email });

// Send `token` to your client

// Client-side: exchange the token for a session-scoped key
const session = await hk.auth.tokenFinish(token);
// session.api_key is a short-lived key scoped to this user
The session key inherits only the scopes the student needs: read:lessons, write:submissions, ai:tutor. It expires in 24 hours.

​
Multiple workspaces

A user with access to several workspaces can list them and switch: 
const platforms = await hk.platforms.list();
// → [{ id: "...", domain: "school-a.example", role: "manager" }, ...]

const a = new Hawkings({ api_key: apiKey, platform: platforms[0].id });
const b = new Hawkings({ api_key: apiKey, platform: platforms[1].id });

​
Rotating a key

Rotating is non-disruptive:
  1. Issue a new key in the dashboard.
  2. Deploy it.
  3. Revoke the old one.
Revoked keys return a 401 authentication_error on the next request.

​
Self-hosted instances

If you’re running Hawkings on your own infrastructure, point the SDK at your base URL: 
new Hawkings({
  api_key: "hk-...",
  base_url: "https://api.your-school.example",
});