Authentication

LinkXG supports two authentication methods: OAuth 2.0 for machine-to-machine integrations, and JWT tokens for user-context operations. This guide covers both.

Authentication methods

Method	Use case	Token lifetime
OAuth 2.0 Client Credentials	Server-to-server integrations, automated systems	15 minutes
JWT Bearer Token	User-initiated actions, interactive applications	15 minutes (access), 7 days (refresh)

For most integrations, OAuth 2.0 is the recommended approach.

OAuth 2.0 (recommended)

OAuth 2.0 Client Credentials flow is designed for machine-to-machine communication where no user interaction is required.

Step 1: Create an OAuth client

OAuth clients are created in the LinkXG application by an Owner or Admin.

Go to Account > API Access
Select Create OAuth Client
Provide a name for the client (e.g., “ERP Integration”)
Select the scopes you need
Save the client

You will receive a client_id and client_secret. Store the secret securely — it is shown only once.

Step 2: Request an access token

Exchange your credentials for an access token:

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 connections:read"

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "products:read connections:read"
}

The token expires in 900 seconds (15 minutes). Request a new token before it expires.

Step 3: Use the token

Include the token in the Authorization header of all API requests:

curl https://api.linkxg.com/api/v1/products \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Available scopes

Scope	Description
`products:read`	Read products and product versions
`products:write`	Create, update, and delete products
`connections:read`	Read connections and shared data
`connections:write`	Manage connections
`imports:write`	Bulk import operations
`traceability:read`	Read traceability and supply chain data
`dpp:read`	Read Digital Product Passports

Request only the scopes you need. Tokens with broader scopes carry greater risk if compromised.

Rotating client secrets

If your client secret is compromised, rotate it immediately:

curl -X POST https://api.linkxg.com/api/v1/oauth/clients/YOUR_CLIENT_ID/rotate \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

This invalidates the old secret and returns a new one. Update your integration before the old secret stops working.

JWT authentication (user context)

JWT authentication is used when actions need to be performed in the context of a specific user, typically for interactive applications.

curl -X POST https://api.linkxg.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your_password"
  }'

Response:

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "dGhpcyBpcyBhIHJlZnJl...",
    "user": {
      "id": "uuid",
      "email": "[email protected]",
      "role": "ADMIN"
    }
  }
}

Using the token

Include the access token in requests:

curl https://api.linkxg.com/api/v1/products \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Refreshing tokens

Access tokens expire after 15 minutes. Use the refresh token to obtain a new access token:

curl -X POST https://api.linkxg.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "YOUR_REFRESH_TOKEN"
  }'

Refresh tokens are rotated on each use — you receive a new refresh token with each refresh request. The old refresh token is invalidated.

Logout

Invalidate your session:

curl -X POST https://api.linkxg.com/api/v1/auth/logout \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Token handling best practices

Store tokens securely. Never store tokens in client-side code, localStorage, or version control. Use secure server-side storage or environment variables. Refresh proactively. Request a new token before the current one expires. A token that expires mid-request will fail. Handle 401 errors gracefully. If you receive a 401 Unauthorized response, your token may have expired. Refresh it and retry the request. Use the minimum necessary scope. Tokens with broader scopes carry greater risk. Request only what you need. Rotate secrets regularly. Even without a suspected compromise, rotating client secrets periodically reduces risk.

Error responses

Authentication errors return standard HTTP status codes:

Status	Error	Description
400	`invalid_request`	Malformed request (missing fields, invalid format)
401	`invalid_client`	Client credentials are incorrect
401	`invalid_token`	Token is expired, malformed, or revoked
403	`insufficient_scope`	Token does not have the required scope
429	`rate_limit_exceeded`	Too many authentication requests

Example error response:

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

Overview

Suppliers

Buyers

Developers

Account & Billing

API Reference

Authentication

Authentication methods

OAuth 2.0 (recommended)

Step 1: Create an OAuth client

Step 2: Request an access token

Step 3: Use the token

Available scopes

Rotating client secrets

JWT authentication (user context)

Using the token

Refreshing tokens

Logout

Token handling best practices

Error responses

Next steps

API Reference

Rate limits

Overview

Suppliers

Buyers

Developers

Account & Billing

API Reference

​Authentication methods

​OAuth 2.0 (recommended)

​Step 1: Create an OAuth client

​Step 2: Request an access token

​Step 3: Use the token

​Available scopes

​Rotating client secrets

​JWT authentication (user context)

​Login

​Using the token

​Refreshing tokens

​Logout

​Token handling best practices

​Error responses

​Next steps

API Reference

Rate limits

Authentication methods

OAuth 2.0 (recommended)

Step 1: Create an OAuth client

Step 2: Request an access token

Step 3: Use the token

Available scopes

Rotating client secrets

JWT authentication (user context)

Login

Using the token

Refreshing tokens

Logout

Token handling best practices

Error responses

Next steps