Authentication
How service tokens work: creating, sending, rotating, and revoking them, plus the status each one can have and what a failed check returns.
The HTTP API authenticates every request except the contract itself with a service token. A service token is an organization-scoped credential that lets a script or integration act on one school’s data. Owners and admins manage tokens under Dashboard → Settings → Integrations.
A token is not a person. It never inherits its creator’s identity, and it keeps working if the person who created it leaves the school, until someone revokes it.
Send the token
Put the token in the Authorization header and nowhere else:
GET /v0/programs?limit=25 HTTP/1.1
Host: api.soljio.com
Authorization: Bearer soljio_sk_REPLACE_WITH_YOUR_TOKEN
A token starts with soljio_sk_ followed by 43 URL-safe characters. The Bearer scheme name is not case-sensitive. Any header that does not match that shape is rejected with 401 before Soljio looks anything up.
Create a token
Only an active owner or admin can create a token. An admin cannot grant scopes that require an owner; those checkboxes are disabled for admins and carry an Owner only label.
Open the Integrations section
In the dashboard, open Settings and go to Integrations. The section reads: Tokens let other tools read or update your data. Each one does only what you allow and can be revoked at any time.
Select Create token
A sheet titled Create token opens.
Name the integration and choose a lifetime
Integration name is required and holds up to 80 characters. Pick the name of the system that will use the token, so you know what stops working if you revoke it. Expires after offers 30 days, 60 days, 90 days (the default), 180 days, and 1 year.
Choose access
Under Access, tick the scopes the integration needs. They are grouped by area: Organization, Programs and offerings, Schedule, Participants, Enrollment and attendance, Progress, Communications, and Administration. Scopes that reach student, guardian, or access-control data carry a Sensitive label. The full list is on the Scopes page.
Copy the secret
Select Create token. The secret appears once. Select Copy token and store it right away.
An organization can hold up to 25 active tokens. If you reach the limit, creating another fails with the message that an organization can have 25 active tokens; revoke one you no longer use first. Expired and revoked tokens do not count. Agent connections do not count either.
Read the token list
Each row shows the integration name, the first characters of the secret (for example soljio_sk_a1B2c3…) so you can match the row to the credential in your system, and a status badge. Under the row you can see when the token expires, when it was last used, who created it, and the access it holds. The Last used time is recorded at a resolution of five minutes, so it can lag a busy integration slightly.
| Status | Meaning |
|---|---|
| Active | The token works until it expires. |
| Superseded | The token was rotated with a grace period. It keeps working until the time shown, then stops. |
| Expired | The lifetime ended. The token no longer works. |
| Revoked | The token was revoked, or was rotated with no grace period. It no longer works. |
When an active token has 14 days or fewer left, its row shows: This token expires soon. Rotate it to keep the integration running.
If the person who created a token loses access to the school, the row says so and adds that the token still works until you revoke it.
Rotate a token
Rotation issues a new secret for the same integration name and the same scopes. Use it before a token expires, or immediately if a secret leaks.
- Open the more-actions menu (…) on the token’s row and choose Rotate….
- Choose Expires after for the new secret.
- Choose Old secret stops working: Now, In 1 hour, or In 24 hours.
- Select Rotate token and copy the new secret.
Choose Now (the default) when a secret leaked. Choose a window only for a planned rotation, when you need time to deploy the new secret before the old one stops. During the window the old token shows as Superseded.
A few rules apply:
- A grace window never extends a token past its original expiry. The old secret stops at the window’s end or its original expiry, whichever comes first.
- A token inside a grace window still counts toward the limit of 25 active tokens, so a window is refused if you are at the limit.
- You cannot rotate a token twice. If a token has been rotated, rotate its replacement.
- You cannot rotate a revoked token.
- Admins cannot rotate a token that holds owner-only scopes.
Revoke a token
Open the more-actions menu (…) on the token’s row, choose Revoke…, and confirm with Revoke token. The dialog warns that the integration using the token stops working immediately and that this cannot be undone. Revocation takes effect on the next request. The row stays in the list so its history remains readable.
What a failed check returns
Soljio is deliberately uninformative about why a credential failed, because that would reveal facts about another school’s account.
| Situation | Response |
|---|---|
| Header missing, malformed, or not a Soljio token | 401 |
| Unknown, revoked, or expired token | 401, identical in every case |
| School suspended | 401, identical to the cases above |
| Valid token, missing scope | 403 |
Every 401 carries WWW-Authenticate: Bearer realm="soljio-api", error="invalid_token". A 403 names the scope that was needed in WWW-Authenticate: Bearer error="insufficient_scope", scope="catalog.write". Use that header to fix an integration. See Errors.
What gets audited
Integration activity is recorded in the school’s Audit log under Settings. Rows caused by a token read API · followed by the token’s name, so a reviewer can tell which integration acted.
- Commands are recorded when they succeed and when they fail.
- Creating, rotating, and revoking a token are recorded, along with a refused request from a known token.
- A read that needs a sensitive read scope is recorded too, because a school must be able to answer who looked at a student’s record and when. Ordinary catalog reads are not recorded.
- The secret and its hash never appear in an audit row.
- A request with an unknown secret is not recorded, because there is no school to attribute it to.
Troubleshooting
- A token worked yesterday and returns 401 today. Check the row under Integrations. It may be Expired or Revoked, or it may have been rotated and its grace window may have ended.
- A rotation seems to have broken an integration. The old secret stopped working because Old secret stops working was set to Now. Deploy the new secret, or rotate again with a grace window next time.
- You lost the secret. It cannot be recovered. Rotate the token to get a new one.