Scenario
As an admin, you want to give an integration, automation, or AI agent access to the PlusPlus API, limited to what it needs. You also want to track which tokens are in use and revoke tokens that are no longer needed.
Which API do these tokens work with? API Tokens dashboard tokens authenticate the PlusPlus Public API v2 only. The endpoints are under /api/v2/; the legacy path /public_api/v2/ is also accepted. Send the token as Authorization: Bearer <token>. These tokens do not authenticate the GraphQL API or the v1 Agent API (/public_api/v1/), which use a separate GraphQL token generated from Settings > Developers. See Setting Up and Managing Per-User Tokens.
Solution
API tokens are managed from the API Tokens dashboard, which is available to admins only.
Do you need a token?
A token lets another app or agent do what you would otherwise do yourself in the dashboard. If you're doing the work in the dashboard, you don't need a token. If another app or agent is doing it, that app needs a token with the matching access.
Task | You do it yourself | An app or agent does it |
Assign content to someone | The content item's Assignment Roster | A token with Assignments: Read & write |
Register a webhook | Dashboard > Webhooks | A token with Webhooks: Read & write |
View existing tokens
Open the profile menu and select Dashboard.
Select API Tokens under Administration in the left sidebar.
The dashboard lists all tokens issued for your site. Each row shows:
Name: the label given to the token at creation.
Key Prefix: the first 8 characters of the token, which identify it without exposing the full secret.
Scopes: a summary of the token's access, such as Full access or 3 scopes + admin.
Created by: the admin who issued the token.
Created: the date the token was issued.
Last used: the most recent time the token authenticated a request, or Never.
Expires: the token's expiration date, or Never.
Status: Active or Revoked.
The table shows 15 tokens per page and can be sorted by name or creation date.
Create a token
From the API Tokens dashboard, click Create token.
The Create API token dialog opens.
Enter a Token name (up to 128 characters) that says what the token is for, for example Assignment tracker – Sheets.
Select an Expiration: 30 days, 60 days, 90 days, 1 year, or Never. The default is Never.
Under Access, select what the token can reach:
Full access (read & write): every area. Includes automated rules unless Grant admin capability is also turned on. This is the default.
Read-only: read access to every area listed under Custom.
Custom: for each area, select Read or Read & write, or leave both cleared for no access.
Leave Grant admin capability off unless the integration needs admin-only operations (see Scopes below).
Click Create token.
The full token appears once, with a Copy button.
Copy the token to your secrets manager immediately. After you close the dialog, the full token can't be retrieved again. Only the Key Prefix stays visible on the dashboard.
Revoke a token
From the API Tokens dashboard, locate the token.
Open the context menu (button with three dots) for that token and select Revoke.
Confirm the action.
The token's status changes to Revoked, and API requests made with it fail. Revocation can't be undone. To restore access, create a new token.
Go deeper
Scopes
Every token carries scopes, one per area it can reach. A read request (GET) needs Read access to the area. Any request that creates, changes, or deletes something needs Read & write, which includes Read. A request outside the token's scopes fails with 403 insufficient_scope and a message naming the missing scope. For example:
This token does not carry the 'webhooks:write' scope required for this operation.
To fix a scope error, create a new token with the access the integration needs. You can't change a token's scopes after creation.
Dialog label | Scope | What it covers |
Content |
| Articles, videos, courses, Guides, links, tracks, scheduled tracks, events, Event Series, channels, collections, tags, locations, office hours, and content item details such as tags, facilitators, access, and cover images |
Assignments |
| Assignments |
Enrollments |
| Event enrollments and course registrations |
Users & groups |
| Users and groups |
Surveys |
| Surveys, survey attachments, and survey responses |
Insights & reports |
| Insights and saved reports |
Webhooks |
| Webhook registrations and their signing secrets |
API tokens |
| Creating, listing, and revoking the token owner's own tokens through the API |
(Full access, without admin capability) |
| Automated rules |
Grant admin capability |
| Admin-only operations, such as reading and changing site settings through the API. It does not add access to any other area. |
Scopes only narrow access; they never add to it. A token created through the API can't carry a scope that the token creating it lacks. Only admins can grant the admin capability.
Who a token acts as
A token works only while the person who created it holds the Admin role. If that person's role changes, their tokens stop working immediately, and requests return 401.
Deactivating an admin doesn't currently revoke their tokens. Before you deactivate someone, revoke their tokens from the API Tokens dashboard. The dashboard shows every admin's tokens, not just your own.
Least privilege
Create one token per integration, so you can revoke one without breaking the others.
Use Custom and grant only the areas the integration uses, with Read unless it needs to make changes.
Set an expiration instead of the default Never wherever the integration allows rotation.
Name each token for its purpose, and check Last used periodically to find tokens to revoke.
Token format and storage
When you create a token, PlusPlus generates a random secret, stores a SHA-256 hash of it, and records the first 8 characters of the secret as the Key Prefix. PlusPlus never stores the full token in plaintext, and the full value cannot be retrieved after the create dialog closes. Always store the token in a secrets manager (for example, Vault or AWS Secrets Manager) rather than in source code or shared documents.
Usage tracking
Each authenticated API request updates the token's Last used timestamp, throttled to once per 60 seconds. Use this column to identify stale or unused tokens that are candidates for revocation.
What you can't do today
Tokens can't be renamed after creation. Revoke the token and create a new one instead.
Token expiration can't be edited after creation. Revoke the token and create a new one instead.
A token's scopes can't be changed after creation. Create a new token with the access you need.
Revoked tokens can't be reactivated or regenerated. Create a new token instead.
Automated rules access is only available with Full access when Grant admin capability is off. It can't be included in Read-only or Custom tokens, or in tokens with admin capability.
The dashboard shows a summary of each token's scopes, not the full list.