Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.firstresonance.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

This page walks you from zero to a working API call. By the end you’ll have:
  • An access token authenticating against your ION organization
  • A successful GraphQL query returning data from your tenant
  • Pointers to the next pages depending on what you’re building
If you’ve never written a GraphQL query before, ION’s field-selection guide explains why you need to ask for fields explicitly — that catches a lot of “the API returned blanks” surprises before they happen.

​
Prerequisites

  • An ION organization (your tenant on *.firstresonance.io)
  • Either an API key (for machine-to-machine integrations) or OAuth credentials (for user-facing applications). See Authentication for how to obtain each.
  • A tool that can make HTTPS POST requests with JSON bodies — curl, httpie, Postman, or a language client.

​
The endpoint

All API requests go to one endpoint: 
POST https://api.firstresonance.io/graphql
Authenticated with: 
Authorization: Bearer <token>
Content-Type: application/json

​
Step 1 — Get an access token

If you have an API key, exchange it for a short-lived access token via your auth provider’s client-credentials grant. Most teams put this in a small client library so it’s transparent — see the Python Quickstart for a copy-paste-able pattern. If you’re using OAuth 2.0, complete the authorization code flow described in Authentication → OAuth 2.0. After the user signs in, your callback receives an access_token. Either way, you end up with a JWT string in your hand. Treat it like a password.

​
Step 2 — Make your first request

A minimal “who am I?” query confirms the token works: 
curl -X POST https://api.firstresonance.io/graphql \
  -H "Authorization: Bearer $ION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { currentUser { id name email organization { id domain } } }"
  }'
A successful response looks like: 
{
  "data": {
    "currentUser": {
      "id": 42,
      "name": "Ada Lovelace",
      "email": "ada@acme.com",
      "organization": {
        "id": 7,
        "domain": "acme.com"
      }
    }
  }
}
If the response is an errors payload instead, jump to Error codes and the 401 table in Authentication — the error message will tell you exactly what to fix.

​
Step 3 — Query something real

Now that auth works, try a domain query. Listing parts is a good first test because it touches inventory, the most common integration target: 
curl -X POST https://api.firstresonance.io/graphql \
  -H "Authorization: Bearer $ION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { parts(filters: {}, limit: 5) { id partNumber description } }"
  }'
You should see up to five parts from your org. If the array comes back empty, your org may not have parts yet — try currentUser again to confirm the token is valid, then check the admin UI for data.
Tip: If you query an entity but the response fields are empty (no id, no partNumber), you almost certainly forgot to select fields explicitly. GraphQL never returns fields you didn’t ask for. See GraphQL Field Selection.

​
Step 4 — Pick your next page

You now have a working integration. Where to go next depends on what you’re building:
If you’re…Go to
Writing scripts in PythonPython Quickstart
Working through 20 common queries by use caseCommon Queries Guide
Building real-time event-driven integrationsWebhooks
Uploading files (procedure attachments, run artifacts)File Upload
Mapping ION’s data model into your systemData Model Reference
Hitting a 403 or unfamiliar errorError Codes
Testing without affecting productionSandbox / Dev Environment

​
Tips

  • Always use the playground first. Mintlify’s API playground lets you write and run queries against your real org without writing client code. Once a query works there, copy it into your application.
  • Set ION_TOKEN as an environment variable during exploration. Don’t paste tokens directly into commands — they end up in shell history.
  • Save your working queries as fragments in your client library. Fragments make it easy to keep field selection consistent across calls and avoid the “I forgot to ask for etag again” pattern.