Authentication

NOTE

To use this API, you need an Edifix account with API access. If you don't have one, contact Edifix Support to get started.

Every Edifix API call except POST /get_auth_token requires a JSON Web Token (JWT) presented as a bearer token:

Authorization: Bearer <jwt>

To obtain a JWT, call POST /get_auth_token with valid Edifix credentials. See the API reference for the full request and response schemas, or the Quick start for a step-by-step guide.

Token lifetime

The expiration field in the get_auth_token request is the requested JWT lifetime in seconds. The server clamps the value to:

• Minimum: 3600 seconds (one hour).
• Maximum: 345600 seconds (four days).
• Omitted or null: the configured default (typically 10800 seconds—three hours by default).

A JWT carries its issued-at and expiry inside its payload; an expired token returns error 0027. A missing token returns 0034; a malformed or otherwise invalid token returns 0026. See Error codes for the full list.

Multi-session JWT management

Edifix Support can enable high-volume customers to maintain multiple concurrent JWTs for the same account. Each concurrent session is rate-limited independently, so a hyperactive worker on one session does not consume the budget of another. See Rate limiting for per-session limits.

A session_tag is an opaque string that identifies which session a JWT belongs to. You choose the value; your client code uses it to find or recreate a session.

Session behaviour differs based on whether your account is single-session or multi-session.

Single-session accounts (the default)

• Every successful get_auth_token call returns a JWT bound to the account's one and only active session.
• Edifix ignores any session_tag value in the request body.
• Calling get_auth_token again refreshes that single session and extends its expiry.

Multi-session accounts

• Reusing an existing session_tag re-authenticates that session, and extends its expiry. The new JWT replaces the previous one for that session.
• Supplying a new tag (or no tag at all) opens a new session if the account has spare session capacity. If no capacity remains the call fails with error 0033.
• If you don't supply a tag and a new session opens, Edifix assigns one internally and embeds it in the issued JWT.

Use a stable, descriptive tag—per worker or container—for example, ingest-worker-3, nightly-batch. Avoid using IP addresses as tags—cloud networks, NAT (Network Address Translation), and proxies often share IPs between clients, which can cause unintended session conflicts.

INFO

To enable multi-session support, contact Edifix Support. This is not a self-service setting.

Business-partner pass-through tokens

Business partners who embed Edifix in their own products can use a pass-through api_token to authenticate their customers' API requests without sharing their own account credentials. The business partner generates the token in the Edifix UI (Account → Settings → API Tokens).

Important properties of the pass-through api_token:

• It is not a replacement for the JWT. Every endpoint other than get_auth_token still requires the JWT in the Authorization header.
• Supply it alongside username and password in the get_auth_token request body. The end user must still have a valid Edifix account with an active subscription because the pass-through token grants API access only.
• It does not expire automatically; tokens remain valid until the business partner explicitly deletes them in the management portal.
• A pass-through call does not implicitly grant multi-session permissions. Enable multi-session on the underlying account separately.
• Any unrecognised pass-through token (including deactivated ones) returns error 0007. The API reserves code 0008 for an "inactive token" message, but does not currently emit it. Invalid and inactive tokens both surface as 0007.

WARNING

Do not route multiple end users' requests through one shared JWT. Each JWT is scoped to a single user account.