Connect to the Fabritec API

This guide shows how a server-side application can connect to Fabritec using standard OAuth 2.0 client credentials. No Fabritec SDK is required.

Connection details

You need four values:

Value	Example	Purpose
Authority	`https://auth.fabritec-eg.com`	The trusted Fabritec identity service that issues access tokens.
Token endpoint	`https://auth.fabritec-eg.com/connect/token`	The authority endpoint used to obtain an access token.
Tenant API base URL	`https://YOUR-TENANT-HOST`	The Fabritec tenant that owns the data. Obtain the exact URL from the tenant administrator.
Client credentials	Client ID and client secret	Identify the integrating application.

The authority is not the business API address. Get the token from auth.fabritec-eg.com, then send that token to the correct tenant host under /api.

1. Create an integration client

A Fabritec administrator with the ManageIntegrations permission must:

Open Settings > Integrations.

Create an External System client.

Assign the client a tenant role containing only the permissions the integration needs. The endpoint and policy catalog lists the permission required by each operation.

Copy the generated client ID and client secret immediately. The plaintext secret is displayed only when the client is created or its secret is rotated.

Store the secret in a server-side secret manager or protected environment variable. Never put it in source control, logs, browser JavaScript, a mobile application, or a URL.

2. Obtain an access token

Send an HTTPS form-encoded request to the token endpoint:

With cURL:

A successful response has this shape:

{
  "access_token": "eyJ...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "fabritec.integration"
}

Treat the token as a secret. Its actual lifetime is the expires_in value returned by the authority; do not assume it will always be 3,600 seconds.

3. Call the tenant API

Send the token only in the Authorization header:

Use the target tenant's live contract at:

https://YOUR-TENANT-HOST/api/openapi.json

Only routes published in that document are supported. Do not send a token in the query string.

Token expiry and renewal

The client-credentials flow normally does not issue a refresh token. Renewal is simple:

Cache the access token in memory.

Read its lifetime from expires_in.

Request a new token about 60 seconds before expiry by repeating the same /connect/token request.

If an API request receives a confirmed 401, discard the cached token, obtain a new token, and retry that request once.

In a multi-threaded service, allow only one worker to renew the token at a time.

Do not request a new token before every API call. Do not automatically replay a timed-out or otherwise ambiguous data-changing request; first reconcile the resource state. Retrying once after an explicit authentication 401 is different because authentication is rejected before the API operation runs.

Complete Python example

This example uses the common requests HTTP library, not a Fabritec SDK. Install it with pip install requests.

Set protected environment variables before starting the application:

FABRITEC_API_BASE=https://YOUR-TENANT-HOST
FABRITEC_CLIENT_ID=YOUR_CLIENT_ID
FABRITEC_CLIENT_SECRET=YOUR_CLIENT_SECRET

For production use, add application-appropriate network retry and telemetry policies. Automatically retry safe reads with bounded exponential backoff and jitter. Honor Retry-After for 429 responses. Never log the access token, client secret, authorization header, or sensitive response bodies.

Common responses

API failures use application/problem+json. Record the returned traceId when contacting Fabritec support.

Status	Meaning	What the integrating application should do
`400`	Invalid request	Correct validation, paging, filtering, sorting, or date-time input.
`401`	Missing, invalid, or expired token	Renew the token and retry once. If it still fails, verify the credentials and authority.
`403`	Authenticated but not allowed	Verify the client is enabled, belongs to the correct tenant, has `fabritec.integration`, and has the required tenant role permissions. Token renewal does not fix a missing permission.
`404`	Route or resource not found	Check `/api/openapi.json` and the resource identifier; do not repeatedly retry.
`409`	Business-state conflict	Read the current state and resolve the conflict.
`429`	Rate limit exceeded	Wait at least the number of seconds in `Retry-After`, then retry according to the operation contract.
`503`	API authentication unavailable	Wait for service availability. Integrations are intentionally unavailable when a tenant runs in offline mode.

Secret rotation and access changes

Rotate a client secret in Settings > Integrations if it may have been exposed or as required by your security policy.

Deploy the new secret to the integrating application immediately. The old secret must no longer be used after rotation.

Disabling a client or removing one of its roles takes effect on the next API request; an already-issued token does not preserve removed business permissions.

Use a separate integration client for each external application and environment so one credential can be revoked without affecting others.

Go-live checklist

The integration runs on a trusted server, not in browser or mobile code.

The API base URL is the exact target tenant host; the authority is https://auth.fabritec-eg.com.

The secret is stored outside source control and is redacted from logs.

The requested scope is exactly fabritec.integration.

Tokens are cached and renewed before expiry; 401 renewal is retried only once.

The application uses only operations published by the tenant's /api/openapi.json.

The client has the minimum roles required by the operations it calls.

The application handles RFC 7807 problems, traceId, Retry-After, timeouts, and ambiguous mutations safely.

Connect to the Fabritec API

Connection details#

1. Create an integration client#

2. Obtain an access token#

3. Call the tenant API#

Token expiry and renewal#

Complete Python example#

Common responses#

Secret rotation and access changes#

Go-live checklist#