How to authenticate

Step 1 — Get the token

Make a POST request with your credentials:

curl -X POST "https://one.fracttal.com/oauth/token" \
  -H "Authorization: Basic $(echo -n 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' | base64)" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials"

If the credentials are correct, you'll get a response like this:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 7200
}

Field	Description
`access_token`	The token you'll use in every request
`token_type`	Always `Bearer`
`expires_in`	Lifetime in seconds (`7200` = 2 hours)

Step 2 — Use the token in your requests

Include the token in the Authorization header of every request:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Full example

curl -X GET "https://one.fracttal.com/hub/api/v1/dags" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

You don't need to send any company identifier as a parameter. The API extracts it automatically from your token.

Step 3 — Renew the token when it expires

The token lasts 2 hours. When it expires you'll see a 401 error. Simply repeat Step 1 to get a new one.

Common issues

I don't have my credentials (`client_id` / `client_secret`)

Credentials are generated by a Fracttal administrator from the Permission Groups section. If you don't have them, contact your account administrator.

The token doesn't work — `401` error

There are several reasons a token can be rejected:

Situation	What to do
You forgot to include the `Authorization` header	Add `Authorization: Bearer <token>` to the request
You misspelled the header (e.g. `Authorisation` or without `Bearer`)	Verify it's exactly `Authorization: Bearer <token>`
The token expired (more than 2 hours have passed)	Request a new one by repeating Step 1
The credentials are incorrect	Verify your `client_id` and `client_secret` with the administrator

Example response when the token expired:

{
  "error_code": "TOKEN_EXPIRED",
  "message": "The provided token has expired",
  "status_code": 401
}

I have a token but I get a `403` error

This means your user has valid credentials but doesn't have permission to use the ETL module.

{
  "error_code": "OAUTH2_ETL_ACCESS_DENIED",
  "message": "This OAuth2 client does not have access to the ETL module",
  "status_code": 403
}

Solution: A Fracttal administrator must enable the Automator → Fracttal Hub permission in the Permission Group associated with your credentials.

Authentication error summary

Code	Cause	Solution
`401`	`Authorization` header missing or misspelled	Check the header format
`401`	Token expired	Request a new token
`401`	`client_id` or `client_secret` incorrect	Verify credentials with the administrator
`403`	No permission for the ETL module	Ask the administrator to enable it