Entrii REST APIs — integration guide

This document describes how consuming applications expose the three Entrii REST surfaces with Laravel Passport and how integrators should authenticate.

Surfaces and base paths

Each group applies middleware for API JSON, Passport authentication, tenant resolution from the access token, throttling, and scope checks. Callers must send:

Authorization: Bearer <access_token>

Tenant binding (no X-Tenant-Id)

The active tenant is determined from the Passport access token (a tenant_id column on oauth_access_tokens, populated when the user authorizes with a tenant_id query parameter on /oauth/authorize). Integrators must not rely on a tenant header or tenant in the URL for routine calls.

To switch tenants, obtain a new access token after authorization for the other tenant.

Authorization request

The Entrii package ships middleware for the web stack that applies to Passport’s authorize endpoint (default path prefix oauth):

• On GET /oauth/authorize, the query must include `tenant_id` (UUID of the tenant). The authenticated user must be allowed to access that tenant (canAccessTenant). The tenant id is stored in session and written through to the issued access token (auth code + access token pipeline implemented in the package).

If the user is not yet logged in when hitting authorize, the middleware may stash a pending tenant id in session until login completes; your login flow should return the user to authorize with the same tenant_id.

Scopes

The Entrii package registers canonical scope names with Passport (Passport::tokensCan(ApiScopes::definitions())). Request only the scopes required for each integration. Route groups require at least one scope from the relevant family (e.g. backoffice:read or backoffice:write for the backoffice API).

Consumer application setup (checklist)

1. Add `laravel/passport` to Composer `dont-discover` so Laravel does not auto-register Passport’s default service provider (Entrii ships EntriiPassportServiceProvider, which extends Passport and wires Entrii’s refresh-token grant). Example in your app composer.json under extra.laravel.dont-discover: "laravel/passport".

2. Run the Passport install steps your team uses (keys, clients, migrations).

3. Use the api authentication guard with the passport driver (see Laravel docs). The package User model already uses Laravel\Passport\HasApiTokens; your App\Models\User can extend Entrii\Models\User without adding the trait.

4. Run package migrations (UUID user_id on OAuth tables, `tenant_id` on Passport tables — see database/migrations/2026_05_04_173500_alter_oauth_token_user_id_for_uuid_users.php and 2026_05_04_220000_add_tenant_id_to_oauth_tables.php in the package).

5. Register ValidateOAuthAuthorizeTenant on the web middleware group so /oauth/authorize enforces tenant_id.

6. Merge or load Entrii api_v1 routes (package service provider) so /api/v1/... endpoints exist.

OAuth client provisioning

How clients are created (CLI only, Filament “API applications”, or a partner portal) is a product decision. Until a self-service flow exists, document for each environment:

• Redirect URIs allowed for each OAuth client.

• Who may create or rotate client secrets.

• Use Authorization Code + PKCE for public/user agents; avoid the password grant.

For machine-only or tests, personal access tokens can be used; the same tenant_id column must be set on the token row if you bypass the authorize flow (see package tests for an example).

OpenAPI

A machine-readable contract skeleton lives next to this file: `openapi.yaml`. Extend it as endpoints are added; keep scopes, error shapes, and money as integers documented there.

Errors

• 401 — Missing or invalid bearer token.

• 403 — Token not bound to a tenant, user cannot access that tenant, insufficient scope, or policy denial.

• 422 — Validation (including missing tenant_id on authorize when required).

Refer to Laravel’s JSON validation format for 422 responses on write endpoints.