> ## 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.

# Getting started

> Make your first authenticated GraphQL request to the ION API.

## 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](/api-reference/authentication/overview).
* A tool that can make HTTPS POST requests with JSON bodies, such as `curl`, `httpie`, or Postman.
* Familiarity with GraphQL.

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

## The endpoint

All API requests go to one endpoint:

```
POST https://api.firstresonance.io/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](/api-reference/guides/python-quickstart).

If you use **OAuth 2.0**, complete the authorization code flow in [Authenticate with OAuth 2.0](/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:

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.firstresonance.io/graphql \
      -H "Authorization: Bearer $ION_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "query": "query { me { id name email organization { id domain } } }"
      }'
    ```
  </Tab>

  <Tab title="Python">
    Install `httpx` (`pip install httpx`), then run:

    ```python theme={null}
    import os
    import httpx

    resp = httpx.post(
        "https://api.firstresonance.io/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](/api-reference/guides/python-quickstart).
  </Tab>
</Tabs>

A successful response looks like this:

```json theme={null}
{
  "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](/api-reference/error-codes) and its [401 table](/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:

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.firstresonance.io/graphql \
      -H "Authorization: Bearer $ION_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "query": "query { parts(filters: {}, first: 5) { edges { node { id partNumber description } } } }"
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    import httpx

    resp = httpx.post(
        "https://api.firstresonance.io/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"])
    ```
  </Tab>
</Tabs>

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

## Related

* [Authentication](/api-reference/authentication/overview)
* [Example requests](/api-reference/examples)