External API overview

The Auth API endpoints external applications use for SSO, token verification, company directory lookups, category lookups, and application-access checks.

Base URL

Local development default:

http://localhost:8081

All application endpoints are versioned under /api/v1.

Security model for external apps

External apps integrate against an application record, not a company. Each application owns:

• a unique appId — the OAuth client_id and the value external apps put in .env as AUTH_APP_ID;
• an RSA key pair — the public key identifies the app during token/revoke/introspect calls and verifies the JWTs the app receives;
• an Allowed URLs list — validates redirect_uri and post_logout_redirect_uri.

The application public key identifies the calling app, but it is not a secret. It is accepted only together with a valid app-signed user JWT or the OAuth flow proof (authorization code + PKCE verifier, or a current refresh token).

For company directory and access-control endpoints under /api/v1/external/**, send both:

Authorization: Bearer <app-signed-user-access-token>
X-App-Public-Key: -----BEGIN PUBLIC KEY-----\nMIIB...\n-----END PUBLIC KEY-----

Rules enforced by the API:

• The public key must belong to an active application.
• The bearer token must be an app-signed access JWT (not an internal UI token).
• The token signature must verify with the resolved application's public key.
• The token's application_id claim must match the application resolved from X-App-Public-Key.
• The token's public_key_fingerprint claim must match the application's current key fingerprint.
• The authenticated user must still be active.
• The user must have an active membership in the company carried in the token's company_id claim, and that company must be subscribed to the application.

For headers, send the PEM with escaped newlines (\n) or send the base64 public-key body. Never embed the application private key anywhere outside the Auth service.

Pagination and search

Paged endpoints use Spring pageable query parameters:

Paged responses follow the standard Spring Page shape:

{
  "content": [],
  "pageable": {},
  "totalElements": 0,
  "totalPages": 0,
  "size": 50,
  "number": 0
}

Public auth endpoints

These endpoints do not require an Authorization header. They are used only by the Authfy UI and never produce application JWTs:

External apps must use the OAuth/OIDC flow — not /api/v1/auth/login — to obtain tokens.

Introspect an application JWT

POST /api/v1/auth/introspect
Content-Type: application/json
X-App-Public-Key: -----BEGIN PUBLIC KEY-----\nMIIB...\n-----END PUBLIC KEY-----

{
  "token": "eyJhbGciOiJSUzI1NiJ9..."
}

Active response:

{
  "active": true,
  "subject": "user-uuid",
  "tokenType": "access",
  "claims": {
    "sub": "user-uuid",
    "email": "member@example.com",
    "company_id": "company-uuid",
    "company_slug": "company-slug",
    "application_id": "application-uuid",
    "app_id": "hrm",
    "public_key_fingerprint": "sha256-fingerprint",
    "token_type": "access"
  }
}

Operational endpoints

Endpoints not intended for external apps

/api/v1/admin/** endpoints are reserved for Authfy administrators. External applications should use /api/v1/oauth/**, /api/v1/external/**, and /api/v1/me/apps instead.

In this section

• OAuth 2.0 / OIDC — the SSO flow and token endpoints.
• Directory endpoints — company, users, categories, applications, current-user apps.
• Management API — app-key authenticated company provisioning and user management.
• JWT verification — verifying Authfy JWTs in Node, Spring, and PHP.