Cirkos GraphQL API

API Reference

The Cirkos API lets you build integrations and automations that connect directly to your Cirkos ERP platform. Query invoices, contacts, sales orders, projects, expenses and more — or automate record creation with mutations.

All data is isolated to your company and enforced at the database level using PostgreSQL Row Level Security.

Endpoint

All GraphQL requests are sent as POST to a single endpoint:

POST https://api.cirkos.cirk-it.co.uk/graphql

The Content-Type header must be application/json. All requests except login, refreshToken and logout require an Authorization: Bearer <token> header.

Quickstart

Get up and running with the Cirkos API in four steps.

1

Log in and get a token

Call the login mutation with your Cirkos credentials.

mutation Login {
  login(
    email: "you@example.com"
    password: "yourpassword"
  ) {
    accessToken
    refreshToken
    accessTokenExpiry
    userId
    companyId
    firstName
    lastName
  }
}

curl -X POST https://api.cirkos.cirk-it.co.uk/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"mutation{login(email:\"you@example.com\",password:\"pw\"){accessToken refreshToken}}"}'

2

Add the Authorization header

Include the access token on every subsequent request.

Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

3

Query your data

Request exactly the fields you need with filtering and sorting.

query {
  invoices(
    where: { status: { eq: "Sent" } }
    order: { dueDate: ASC }
  ) {
    invoiceId
    invoiceNumber
    total
    dueDate
    contact { name email }
  }
}

{
  "data": {
    "invoices": [{
      "invoiceId": 1,
      "invoiceNumber": "INV-001",
      "total": 1250.00,
      "dueDate": "2026-08-07T00:00:00Z",
      "contact": { "name": "Acme Ltd", "email": "billing@acme.co.uk" }
    }]
  }
}

4

Refresh your token

Access tokens expire after 2 hours. Use the refresh token (30 days) to get a new pair.

mutation {
  refreshToken(refreshToken: "your-refresh-token") {
    accessToken
    refreshToken
    accessTokenExpiry
  }
}

Authentication

The Cirkos API uses JWT signed with HS512. Every token is scoped to a single company — enforced at the database level via PostgreSQL Row Level Security.

ℹ️ login, refreshToken and logout are public. All other operations require Authorization: Bearer <token>.

accessTokenJWT stringValid for 2 hours. Send in the Authorization header on every request.

refreshTokenopaque stringValid for 30 days. Use only to call refreshToken mutation. Revoked on logout.

Auto-generated from live schema

Module Reference

Field references below are loaded directly from the live GraphQL schema via introspection. They are always up to date.

Loading schema from API...

Error codes

All errors are returned in the GraphQL errors array with a code extension. HTTP status is always 200 — check the errors field.

Code	Description	Equivalent
NOT_FOUND	Resource does not exist or is not accessible by your company.	404
VALIDATION_ERROR	Invalid credentials, missing fields, or business rule violation.	422
CONFLICT	Duplicate record or state conflict.	409
INTERNAL_ERROR	Unexpected server error. Contact support if this persists.	500

{
  "errors": [{
    "message": "Invoice not found",
    "path": ["invoice"],
    "extensions": { "code": "NOT_FOUND" }
  }],
  "data": null
}

Rate limits

General API100 / minAll queries and mutations. Returns HTTP 429 when exceeded.

Login mutation5 / minStricter limit to prevent brute force attacks.

Status

GraphQL API api.cirkos.cirk-it.co.uk/graphql

Security

TransportTLS 1.3All traffic encrypted via HTTPS. HTTP requests redirected automatically.

AuthJWT HS512Tokens signed with HMAC-SHA512. Passwords hashed with BCrypt (cost 11).

Data isolationRLSPostgreSQL Row Level Security enforces complete isolation between companies at the database level.

Rate limitingFixed windowPer-IP rate limiting. Stricter limits on login to prevent credential stuffing.