YionStack DevelopersSign in

Getting started

Integrate with the YionStack API in 5 steps. You will register an app, authorize a user, and make your first API call.

Step 1 — Register a developer app

Go to Settings → Developer in your YionStack dashboard and click Register app.

Enter your app name, a redirect URI (where users will be sent after authorization), and select the scopes your app needs.

After registration you will receive:

  • client_id — identifies your app (safe to expose)
  • client_secret — authenticates your app (keep secret, shown once only)

Step 2 — Redirect the user to authorize

When a user wants to connect their YionStack account, redirect them to:

https://api.yionstack.co.uk/api/v1/oauth/authorize
  ?response_type=code
  &client_id=yion_your_client_id
  &redirect_uri=https://yourapp.com/callback
  &scope=read:invoices read:contacts
  &state=random_csrf_token

The user will see a consent screen and approve access. YionStack then redirects to your redirect_uri with a code parameter.

Step 3 — Exchange the code for tokens

curl -X POST https://api.yionstack.co.uk/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "the_code_from_redirect",
    "client_id": "yion_your_client_id",
    "client_secret": "ysk_your_secret",
    "redirect_uri": "https://yourapp.com/callback"
  }'

Response:

{
  "access_token": "eyJ...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "dGhp...",
  "scope": "read:invoices read:contacts"
}

Step 4 — Make your first API call

curl https://api.yionstack.co.uk/api/v1/accounting/invoices \
  -H "Authorization: Bearer your_access_token" \
  -H "x-business-id: the_business_uuid"

Response:

[
  {
    "id": "inv_abc123",
    "number": "INV-2026-0001",
    "status": "SENT",
    "total": "1200.00",
    "currency": "GBP",
    "customerId": "cont_xyz789"
  }
]

Step 5 — Handle token refresh

Access tokens expire after 1 hour. Use the refresh token to get a new pair:

curl -X POST https://api.yionstack.co.uk/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "your_refresh_token",
    "client_id": "yion_your_client_id",
    "client_secret": "ysk_your_secret"
  }'

Using an SDK

Instead of raw HTTP calls, use an official SDK:

TypeScript

npm install @yionstack/sdk

import { YionStackClient } from '@yionstack/sdk';
const client = new YionStackClient({ token: tokens.access_token });
const invoices = await client.invoices.list('business-uuid');

Python

pip install yionstack

from yionstack import YionStackClient
client = YionStackClient(token=tokens.access_token)
invoices = client.invoices.list("business-uuid")

Next steps