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": "user@company.com",
    "password": "your_password"
  }'

Response:

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "dGhpcyBpcyBhIHJlZnJl...",
    "user": {
      "id": "uuid",
      "email": "user@company.com",
      "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"

The LinkXG web application signs in through a separate, browser-first authentication surface under /auth/v2. Instead of returning tokens in the response body, these endpoints set the access, refresh, and CSRF tokens as HttpOnly cookies scoped to .linkxg.com. This is the path that powers passwordless sign-in (magic links) and single sign-on (SSO). It is intended for first-party browser clients; server-to-server integrations should continue to use OAuth 2.0. All /auth/v2 endpoints are public (no bearer token required) and enforce an Origin/Referer allowlist. On the JSON endpoints (login, refresh, logout, and the magic-link pair) a request that carries an Origin header which is not on the allowlist is rejected with 403; the SSO redirect endpoints fail the flow rather than returning JSON. State-changing requests authenticated by the session cookie must also carry the X-CSRF-Token header matching the linkxg_csrf cookie.

Cookies issued

Cookie	Purpose
`linkxg_session`	Short-lived access token (`HttpOnly`)
`linkxg_refresh`	Refresh token, rotated on each use with reuse detection (`HttpOnly`)
`linkxg_csrf`	Double-submit CSRF token, echoed back in the `X-CSRF-Token` header

POST /auth/v2/login (email + password), POST /auth/v2/refresh (rotates the session from the linkxg_refresh cookie; returns 204 with no body), and POST /auth/v2/logout (revokes the session and clears the cookies; idempotent, returns 204) round out the session lifecycle. Magic links let a user sign in without a password. Request a link, then redeem the token it carries for a cookie session. Step 1 — request the link:

curl -X POST https://api.linkxg.com/api/v1/auth/v2/magic-link/request \
  -H "Content-Type: application/json" \
  -d '{ "email": "user@company.com" }'

To prevent account enumeration, this endpoint always returns 200 with a fixed message, whether or not the address maps to an account:

{ "success": true, "message": "If that address is registered, a sign-in link is on its way." }

The email contains a link whose single-use token is placed in the URL fragment (#token=…), not the query string, so it never reaches server logs. The client reads the token from location.hash and submits it in the request body — it must not be forwarded from the URL search parameters. Step 2 — redeem the token:

curl -X POST https://api.linkxg.com/api/v1/auth/v2/magic-link/redeem \
  -H "Content-Type: application/json" \
  -d '{ "token": "MAGIC_LINK_TOKEN" }'

Redeem accepts two kinds of token. An existing-user sign-in token sets the session cookies and returns the signed-in user — it materialises a session for a user whose company already exists and does not create a company:

{
  "success": true,
  "message": "Signed in.",
  "data": {
    "user": {
      "id": "uuid",
      "email": "user@company.com",
      "firstName": "Ada",
      "lastName": "Lovelace",
      "role": "ADMIN",
      "tenantId": "uuid",
      "tenant": { "id": "uuid", "name": "Acme Ltd", "slug": "acme", "subscriptionTier": "SUPPLIER_FREE" }
    }
  }
}

A passwordless sign-up intent token provisions the tenant and user at redeem and then signs them in, returning the same envelope. If the sign-up instead resolves to a domain that gates joins, redeem creates an inactive user plus a join request and returns 200 with no cookies:

{ "success": true, "status": "pending_approval", "message": "Your request to join is awaiting approval." }

An invalid, expired, or already-used token returns 400 INVALID_OR_EXPIRED with details withheld.

Single sign-on (SSO)

SSO uses the OIDC Authorization Code flow with PKCE against Microsoft Entra (microsoft) and Google (google). Step 1 — start the flow. Redirect the browser to the start endpoint. It generates a PKCE verifier and challenge, stores single-use OIDC state in Redis (10-minute TTL), and 302-redirects to the identity provider. The optional returnTo query parameter (a path, validated server-side) controls where the user lands after sign-in.

GET https://api.linkxg.com/api/v1/auth/v2/sso/microsoft/start?returnTo=/manual

Step 2 — handle the callback. The provider redirects back to the callback endpoint with code and state. The server validates the state, exchanges the code for tokens, verifies the claims, and resolves the user:

a returning SSO user or a new tenant founder is issued a v2 cookie session and redirected to returnTo;
an existing same-email account is sent through magic-link confirmation;
a domain join that needs owner/admin approval creates a join request and no session is issued.

GET https://api.linkxg.com/api/v1/auth/v2/sso/microsoft/callback?code=…&state=…

Both SSO endpoints respond with redirects (302) rather than JSON, so they are driven by the browser, not called directly by an integration.

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

Cookies issued

Single sign-on (SSO)

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

​Cookie sessions (/auth/v2)

​Cookies issued

​Magic-link sign-in

​Single sign-on (SSO)

​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

Cookie sessions (`/auth/v2`)

Cookies issued

Magic-link sign-in

Single sign-on (SSO)

Token handling best practices

Error responses

Next steps