---
title: Quickstart
description: 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.

1. **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.

2. **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:

    ```bash
    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.

3. **List your programs**

    ```bash
    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`:

    ```json
    {
      "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](/developers/pagination).

4. **Read one program**

    Use the `id` from the list:

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

5. **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:

    ```bash
    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
    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](/developers/idempotency).

:::note[Setting a status other than draft]
Creating a program with any `status` other than `draft` also needs the `catalog.publish` scope. See [Scopes](/developers/scopes) for these conditional grants.
:::

## 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

- [Authentication](/developers/authentication) covers lifetimes, rotation, and revocation.
- [Requests and responses](/developers/requests-and-responses) lists every convention in one place.
- The [API reference](/api) documents every operation.
