Use the API with tokens

In this guide you create an API token, use it from a script and from CI, and connect an AI assistant to the panel through its MCP endpoint.

Prerequisites

A panel account. A token acts as you, with exactly your permissions.

Steps

1. Issue a token

From Settings → API tokens, or with a session token:

PANEL=https://panel.example.com
J='Content-Type: application/json'

ACCESS=$(curl -sX POST $PANEL/auth/login -H "$J" \
  -d '{"email": "you@example.com", "password": "…"}' | jq -r .access)

curl -sX POST $PANEL/me/security/tokens -H "Authorization: Bearer $ACCESS" -H "$J" \
  -d '{"name": "ci-deploy", "expiresInDays": 90}'
# → {"token": {"id": 5, "name": "ci-deploy", "expires_at": "…"}, "plain": "gsl_…", "warning": "…"}

plain is shown once. Only a hash is stored. Leave out expiresInDays for a token that doesn’t expire.

If your account has 2FA, /auth/login returns {"mfaRequired": true, "challenge": "…"}. Exchange it within 5 minutes:

curl -sX POST $PANEL/auth/login/mfa -H "$J" -d '{"challenge": "…", "code": "123456"}'

2. Call the API

Send the token in either header:

TOKEN=gsl_xxxxxxxxxxxxxxxx
curl -s $PANEL/apps/ -H "Authorization: Bearer $TOKEN"
curl -s $PANEL/apps/ -H "X-API-Token: $TOKEN"

Errors use one envelope:

{"error": {"status": 403, "code": "forbidden", "message": "…", "details": null}}

The full surface is in the HTTP API reference. A live OpenAPI 3.1 document and Swagger UI are served by the panel under /docs/ (see API overview).

3. Deploy from CI

A GitHub Actions job that builds a Dart binary and deploys it to a binary app:

name: deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dart-lang/setup-dart@v1
      - run: dart pub get && dart compile exe bin/server.dart -o build/app
      - name: Upload and deploy
        env:
          PANEL: https://panel.example.com
          TOKEN: ${{ secrets.GISILA_TOKEN }}
          APP_ID: "42"
        run: |
          ARTIFACT=$(curl -fsSX POST "$PANEL/apps/$APP_ID/deployments/artifacts" \
            -H "Authorization: Bearer $TOKEN" \
            -H 'Content-Type: application/octet-stream' \
            --data-binary @build/app | jq -r .artifactId)
          curl -fsSX POST "$PANEL/apps/$APP_ID/deployments/" \
            -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
            -d "{\"sourceType\": \"binary\", \"artifactId\": \"$ARTIFACT\"}"

Give CI a token from an account that only has the developer role on the team it deploys to.

4. Connect an AI assistant (MCP)

POST /mcp is a Model Context Protocol server (Streamable HTTP, stateless). With Claude Code:

claude mcp add --transport http gisila https://panel.example.com/mcp \
  --header "Authorization: Bearer gsl_xxxxxxxxxxxxxxxx"

The assistant gets three tools, generated from the panel’s OpenAPI document:

Tool	Does
`search_api`	Finds routes by keywords, with their parameters and body. With no query, lists the route groups.
`api_get`	Calls a GET route. Marked read-only.
`api_change`	Calls a POST, PUT, PATCH or DELETE route. Marked destructive, so clients ask before each call.

Every call is a normal API request with the same validation, rate limits and audit log. Sign-in, webhook deliveries and file uploads (binary and ZIP deploys) aren’t available through MCP.

5. Revoke a token

curl -s $PANEL/me/security/tokens -H "Authorization: Bearer $TOKEN" | jq '.results[] | {id, name, last_used_at}'
curl -sX DELETE $PANEL/me/security/tokens/5 -H "Authorization: Bearer $TOKEN"

Revoking cuts off scripts and assistants that use it immediately. Signing out other sessions (POST /auth/sessions/revoke) doesn’t affect API tokens.

Verify it works

curl -s $PANEL/auth/me -H "Authorization: Bearer $TOKEN" | jq '{email, is_superuser}'