> ## Documentation Index
> Fetch the complete documentation index at: https://docs.linkxg.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started

> Quick start guide for integrating with the LinkXG API

This guide walks you through making your first API calls to LinkXG. By the end, you will have working authentication and be able to retrieve product data.

## Prerequisites

Before you start, you need:

* A LinkXG account with Owner or Admin role
* A subscription tier that includes API access (Supplier Plus or higher for suppliers, Core or higher for buyers)

If you are on a free tier, you can still follow along using the application UI, but API access requires an upgrade.

***

## Step 1: Create an OAuth client

OAuth clients are how your integration authenticates with LinkXG.

1. Log into LinkXG at [app.linkxg.com](https://app.linkxg.com)
2. Go to **Account > API Access**
3. Select **Create OAuth Client**
4. Enter a name (e.g., "My Integration")
5. Select the scopes you need:
   * `products:read` — to retrieve products
   * `connections:read` — to see your connections
6. Select **Create**

You will see your `client_id` and `client_secret`. Copy the secret now — it is shown only once.

***

## Step 2: Get an access token

Exchange your credentials for an access token:

```bash theme={null}
curl -X POST https://api.linkxg.com/api/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=products:read"
```

**Response:**

```json theme={null}
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "products:read"
}
```

Save the `access_token`. You will use it for all subsequent requests.

***

## Step 3: Make your first request

Retrieve your products:

```bash theme={null}
curl https://api.linkxg.com/api/v1/products \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "sku": "WIDGET-001",
      "name": "Industrial Widget",
      "category": "Components",
      "status": "ACTIVE",
      "createdAt": "2025-06-15T10:30:00Z",
      "updatedAt": "2025-12-01T14:22:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalItems": 1,
    "totalPages": 1
  }
}
```

***

## Step 4: Retrieve a specific product

Get full details for a product:

```bash theme={null}
curl https://api.linkxg.com/api/v1/products/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "sku": "WIDGET-001",
    "name": "Industrial Widget",
    "description": "High-precision industrial widget for manufacturing applications",
    "category": "Components",
    "status": "ACTIVE",
    "attributes": [
      {
        "family": "Specifications",
        "name": "Weight",
        "value": 2.5,
        "unit": "kg"
      },
      {
        "family": "Specifications",
        "name": "Material",
        "value": "Stainless Steel"
      }
    ],
    "certifications": [
      {
        "name": "ISO 9001",
        "validUntil": "2027-03-15"
      }
    ],
    "version": {
      "number": 3,
      "publishedAt": "2025-12-01T14:22:00Z"
    }
  }
}
```

***

## Common operations

### List products with pagination

```bash theme={null}
curl "https://api.linkxg.com/api/v1/products?page=1&pageSize=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Filter products by category

```bash theme={null}
curl "https://api.linkxg.com/api/v1/products?category=Components" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### List your connections

```bash theme={null}
curl https://api.linkxg.com/api/v1/connections \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### View shared products from a supplier

```bash theme={null}
curl "https://api.linkxg.com/api/v1/connections/CONNECTION_ID/products" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

***

## Handling token expiry

Access tokens expire after 15 minutes. Before making requests, check if your token is about to expire and request a new one:

```javascript theme={null}
let accessToken = null;
let tokenExpiresAt = 0;

async function getAccessToken() {
  // Refresh if token expires in less than 60 seconds
  if (Date.now() >= tokenExpiresAt - 60000) {
    const response = await fetch('https://api.linkxg.com/api/v1/oauth/token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        grant_type: 'client_credentials',
        client_id: CLIENT_ID,
        client_secret: CLIENT_SECRET,
        scope: 'products:read'
      })
    });
    
    const data = await response.json();
    accessToken = data.access_token;
    tokenExpiresAt = Date.now() + (data.expires_in * 1000);
  }
  
  return accessToken;
}

async function apiRequest(endpoint) {
  const token = await getAccessToken();
  
  return fetch(`https://api.linkxg.com/api/v1${endpoint}`, {
    headers: { 'Authorization': `Bearer ${token}` }
  });
}
```

***

## What's next

Now that you have working authentication, explore the full API:

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference">
    Complete endpoint documentation
  </Card>

  <Card title="Rate limits" icon="gauge" href="/developers/rate-limits">
    Understand usage limits
  </Card>

  <Card title="Error handling" icon="triangle-exclamation" href="/developers/errors">
    Handle errors gracefully
  </Card>

  <Card title="Authentication" icon="key" href="/developers/authentication">
    Deep dive into auth options
  </Card>
</CardGroup>