Keys & permissions
Give each connection a clear purpose and just enough access.
Create a key
- Activate Lite or Pro in Wingman Billing. Open Wingman Developers, sign in with the same Wingman account, then open Connections & API and select Create key.
- Name the connection, choose its permissions and select an expiry of 30 days, 90 days or one year.
- Copy the key once and store it in your tool’s secret store. Wingman stores a fingerprint and cannot reveal it again.
Choose what it can do
Permissions are independent. A practice-paper assistant usually needs questions:read, papers:write and papers:read. An automated marking assistant usually needs marking:submit and marking:read. Starting from a saved Builder paper also requires papers:read.
Reading marked work covers the owner’s marking area, including drafts and in-progress work. API keys cannot manage other keys, change account details, or access administration.
Lite and Pro include developer access. Lite exposes full Pathway through a scoped agent while its browser app shows baseline results. Existing keys never gain new permissions automatically: create a replacement key to add progress:read or mapping:write. Downgrading pauses API access with billing_upgrade_required (402), preserving each key’s scopes, expiry and revocation state. You can still inspect and revoke keys, and manage billing in the main app.
Use marking:import for complete evidenced results. Progress endpoints do not accept raw scores or profile records. Wingman automated marking uses standard credits; Lite has no included marking allowance, and purchased packs can be used.
| Permission | Access |
|---|---|
| questions:read | Search published questions; read their content, schemes and diagrams. |
| papers:read | Read your saved Builder papers and prepared PDFs. |
| papers:write | Create and update papers; prepare PDFs. |
| marking:read | Read your uploaded scans, marking sessions and results. |
| marking:submit | Upload work and request Wingman automated marking. |
| marking:import | Upload and submit externally marked work. |
| marking:review | Edit existing mark decisions and annotations. |
| progress:read | Read your personalised Pathway, skill profile, evidence history and mappings. |
| mapping:write | Correct question and criterion mappings against owned evidence and the current revision. |
Authenticate a request
Use the Authorization header on every request, including private file downloads. The public API does not accept a browser session as authentication.
curl "https://api.wingman.st/v1/me" \
-H "Authorization: Bearer $WINGMAN_API_KEY"Replace or revoke
Create a replacement to change a key’s permissions. Move the connection to the replacement, then revoke the old key. You can have up to 20 active keys.
Revocation stops new requests immediately; already accepted work may finish. Keys also stop working on expiry or when the account is no longer verified. Account restrictions still apply to API requests.
Track usage
The key list shows lifetime requests, errors and the last use time. Open Usage for a 30-day breakdown by UTC date, operation and response status.
Usage records contain counts and timings, not keys, request bodies, scan content or search terms. These are API request counts, not model-token usage or a billing statement.