Skip to content
Soljio Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

Quickstart

Create a service token, read your school's programs with curl, and send your first write request in a few minutes.

This guide takes you from nothing to a working API call. You need to be an owner or admin of the school you want to connect, because only owners and admins can create tokens.

The examples use the production API at https://api.soljio.com/v0. Replace the placeholder token with your own, and never paste a real token into code you commit.

Create a token

Sign in to your school’s dashboard and open Settings, then the Integrations section.

  1. Select Create token.
  2. Enter an Integration name, such as Attendance sync. Names can be up to 80 characters.
  3. Leave Expires after at 90 days, or choose 30 days, 60 days, 180 days, or 1 year.
  4. Under Access, tick Read programs and offerings. Add Manage programs and offerings as well if you want to try the write request later in this guide.
  5. Select Create token.

Soljio shows the secret once, in a box labelled New secret for followed by your integration name. Select Copy token and store it in a secret manager. Soljio keeps only a hash, so it cannot show the secret again.

Keep the token out of your shell history

Read the token into an environment variable for this session. The prompt hides what you paste, so the secret is not saved in your shell history:

read -rs SOLJIO_TOKEN && export SOLJIO_TOKEN

Paste the token and press Enter. In scripts and scheduled jobs, load the token from your secret manager instead of typing it.

List your programs

curl -sS "https://api.soljio.com/v0/programs?limit=25" \
  -H "Authorization: Bearer $SOLJIO_TOKEN"

A successful response is a JSON object with data, next_cursor, and request_id:

{
  "data": [
    {
      "object": "program",
      "id": "PROGRAM_ID",
      "organization_id": "ORGANIZATION_ID",
      "name": "Learn to Swim",
      "slug": "learn-to-swim",
      "status": "active",
      "created_at": "2026-01-05T17:04:11.000Z",
      "updated_at": "2026-01-05T17:04:11.000Z"
    }
  ],
  "next_cursor": null,
  "request_id": "00000000-0000-4000-8000-000000000001"
}

When next_cursor is not null, there are more pages. See Pagination.

Read one program

Use the id from the list:

curl -sS "https://api.soljio.com/v0/programs/PROGRAM_ID" \
  -H "Authorization: Bearer $SOLJIO_TOKEN"

Create a program

Commands are POST requests to /v0/commands/{operation}. They need a JSON body and an Idempotency-Key header. This one needs the catalog.write scope:

curl -i -sS -X POST "https://api.soljio.com/v0/commands/create_program" \
  -H "Authorization: Bearer $SOLJIO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-program-learn-to-swim-2026-01" \
  -d '{"name":"Learn to Swim","status":"draft"}'

The API answers 201 Created with a Location header that points at the new program:

HTTP/2 201
location: /v0/programs/PROGRAM_ID
x-request-id: 00000000-0000-4000-8000-000000000002

{"data":{"ok":true,"program_id":"PROGRAM_ID"},"idempotent_replay":false,"request_id":"00000000-0000-4000-8000-000000000002"}

Send the same request again with the same key and you get the original result back with "idempotent_replay": true and no second program. See Idempotency.

If something goes wrong

What you see Likely cause Fix
401 with unauthorized The token is missing, mistyped, revoked, expired, or belongs to a suspended school Check the header is exactly Authorization: Bearer soljio_sk_... and the token is still listed as Active under Integrations
403 with forbidden The token lacks a scope Read the WWW-Authenticate response header; its scope value names the missing scope. Create a new token that includes it
400 mentioning Idempotency-Key A command was sent without the header, or the key is not 1 to 128 visible ASCII characters Add a valid Idempotency-Key
415 with unsupported_media_type A POST was sent without Content-Type: application/json Add the header

A token’s access is fixed when it is created, and rotating a token keeps the same access. To change what an integration can do, create a new token with the scopes you want and revoke the old one.

Next steps

Was this page helpful?