## Prerequisites

- An ION organization.
- An **API key** for machine-to-machine integrations, or **OAuth credentials** for user-facing applications. For how to obtain each, see [Authentication](https://docs.firstresonance.io/api-reference/authentication).
- A tool that can make HTTPS POST requests with JSON bodies, such as `curl`, `httpie`, or Postman.
- Familiarity with GraphQL.

New to GraphQL? See the [official GraphQL documentation](https://graphql.org/learn/).

## The endpoint

All API requests go to one endpoint:

```
POST https://api.buildwithion.com/graphql
```

Authenticate each request with these headers:

```
Authorization: Bearer <token>
Content-Type: application/json
```

## Get an access token

If you have an **API key**, exchange it for a short-lived access token through your auth provider’s client-credentials grant. For a reusable pattern, see the [Build an API client](https://docs.firstresonance.io/api-reference/guides/python-quickstart). If you use **OAuth 2.0**, complete the authorization code flow in [Authenticate with OAuth 2.0](https://docs.firstresonance.io/api-reference/authentication/oauth). After the user signs in, your callback receives an `access_token`. Both paths give you a JWT string. Treat it like a password.

## Make your first request

A minimal “who am I?” query confirms the token works:

- cURL

```
curl -X POST https://api.buildwithion.com/graphql \
  -H "Authorization: Bearer $ION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{\n    "query": "query { me { id name email organization { id domain } } }"
  }'
```

Install `httpx` (`pip install httpx`), then run:

```
import os
import httpx

resp = httpx.post(
    "https://api.buildwithion.com/graphql",
    headers={"Authorization": f"Bearer {os.environ['ION_TOKEN']}"},
    json={"query": "query { me { id name email organization { id domain } } }"},
)
resp.raise_for_status()
print(resp.json()["data"]["me"])
```

For a reusable client with retries and error handling, see the [Build an API client](https://docs.firstresonance.io/api-reference/guides/python-quickstart).

A successful response looks like this:

```
{
  "data": {
    "me": {
      "id": 42,
      "name": "Ada Lovelace",
      "email": "ada@acme.com",
      "organization": {
        "id": 7,
        "domain": "acme.com"
      }
    }
  }
}
```

If the response is an `errors` payload instead, see [Error codes](https://docs.firstresonance.io/api-reference/error-codes) and its [401 table](https://docs.firstresonance.io/api-reference/error-codes#401-unauthorized).

## Query data

Once auth works, try a domain query. Listing parts is a good first test because it touches inventory, the most common integration target:

- cURL

```
curl -X POST https://api.buildwithion.com/graphql \
  -H "Authorization: Bearer $ION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{\n    "query": "query { parts(filters: {}, first: 5) { edges { node { id partNumber description } } } }"
  }'
```

```
import os
import httpx

resp = httpx.post(
    "https://api.buildwithion.com/graphql",
    headers={"Authorization": f"Bearer {os.environ['ION_TOKEN']}"},
    json={"query": "query { parts(filters: {}, first: 5) { edges { node { id partNumber description } } } }"},
)
resp.raise_for_status()
print(resp.json()["data"]["parts"]["edges"])
```

The response should contain up to five parts from your org. If the response comes back empty, your org might not have parts yet. Query `me` again to confirm the token is valid. Then check the admin UI for data.

## 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 |
| --- | --- |
| Building a reusable API client | [Build an API client](https://docs.firstresonance.io/api-reference/guides/python-quickstart) |
| Working through common queries and mutations | [Example requests](https://docs.firstresonance.io/api-reference/examples) |
| Building real-time event-driven integrations | [Set up webhooks](https://docs.firstresonance.io/api-reference/guides/webhooks) |
| Uploading files, such as procedure attachments and run artifacts | [Upload a file](https://docs.firstresonance.io/api-reference/guides/file-upload) |
| Mapping ION’s data model into your system | [Data model](https://docs.firstresonance.io/api-reference/data-model) |
| Hitting a 403 or unfamiliar error | [Error codes](https://docs.firstresonance.io/api-reference/error-codes) |
| Testing without affecting production | [Sandbox](https://docs.firstresonance.io/api-reference/sandbox) |
| Taking an integration to production | [Build a production integration](https://docs.firstresonance.io/api-reference/guides/build-a-production-integration) |