Authentication¶

Invora uses OpenID Connect (OIDC) for authentication. All API calls require a valid JWT bearer token.

Authentication Methods¶

1. Client Credentials (Machine-to-Machine)¶

For server-to-server integrations. Uses the OIDC client credentials you received during registration.

RequestResponse

# Exchange credentials for an access token
curl -X POST https://auth.invora.app/oauth/v2/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=openid"

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 43200
}

2. Authorization Code + PKCE (User-Facing Apps)¶

For Flutter/web apps where a user logs in interactively.

Redirect to: https://auth.invora.app/oauth/v2/authorize?client_id=...&response_type=code&code_challenge=...&redirect_uri=...&scope=openid profile email
User authenticates via Invora's identity provider
Exchange the authorization code for tokens at /oauth/v2/token

3. Personal Access Token (Development Only)¶

Development only

Personal Access Tokens are intended for local testing and quick debugging only. Do not use them in production integrations or automated systems.

For quick testing. Create a PAT in the Invora admin console under your machine user.

Request

curl -X POST https://stg-gateway.invora.app/api/v1/simple/invoices/list \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PAT" \
  -d '{}'

Using the Token¶

Include the JWT in every API request:

Authorization: Bearer eyJhbGciOi...

Multi-Org Access¶

Invora supports cross-organization access. To act on behalf of a different org (e.g., a platform managing its connected businesses):

X-Target-Org-Id: <target-org-id>

The calling user must have appropriate roles granted on the target organization.

Token Claims¶

The JWT contains:

Claim	Description
`sub`	User ID
`org_id`	User's home organization ID
`roles`	Granted roles per organization

Scopes¶

Each API endpoint requires a specific scope (e.g., Invora.Simple.Invoices.v1.Modify.Create). Scopes are checked against the authz rules engine at runtime. The super admin can modify which roles grant which scopes without code changes.

Token Refresh¶

Access tokens expire after 12 hours by default. Use the refresh token to get a new access token:

Request

curl -X POST https://auth.invora.app/oauth/v2/token \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID"

OIDC Endpoints¶

Endpoint	URL
Discovery	`https://auth.invora.app/.well-known/openid-configuration`
Authorization	`https://auth.invora.app/oauth/v2/authorize`
Token	`https://auth.invora.app/oauth/v2/token`
Userinfo	`https://auth.invora.app/oidc/v1/userinfo`
JWKS	`https://auth.invora.app/oauth/v2/keys`