API Operations

The API System page explains the credentials the starter issues. This page is for running them: the keys they depend on, what each rotation invalidates, the tasks that clean them up, and the situations in which the starter refuses to issue or use them.

Signing Keys

Passport signs every access token with an RSA key pair.

• Deployed environments set the keys in PASSPORT_PRIVATE_KEY and PASSPORT_PUBLIC_KEY. Generate a pair with openssl in a temporary directory, store the contents of the two files in the environment’s secrets, and delete them. See OAuth Signing Keys.
• Locally, php artisan db:rebuild generates key files in storage/ when they don’t exist.
• Each environment has its own pair, shared by all of its instances.

Rotating the signing keys revokes every token

Every access token is signed with the private key. Replacing the key pair makes every outstanding access token invalid at once. Integrations recover by requesting new access tokens with their existing client credentials, and applications and AI clients by refreshing or reconnecting. Personal access tokens can’t be reissued: they stop working for good, still listed as active, and their owners have to create new ones.

What Each Rotation Invalidates

Rotating	Stops working	Keeps working
The signing keys	Every access token, including personal access tokens	Client secrets, refresh tokens
APP_KEY	Refresh tokens and unredeemed authorization codes, which Passport encrypts with it	Access tokens, client secrets
A service client (Rotate in Administration)	Nothing at first: the old client works until you revoke it	Both clients, until the old one is revoked
An application’s secret (Regenerate Secret)	The old secret, at once	Access and refresh tokens already issued

After rotating APP_KEY, applications and AI clients can’t refresh their tokens and have to send people through the consent screen again once their access tokens expire.

Cleanup and Revocation

The scheduler keeps the credential tables accurate. See Scheduled Tasks for the cadences.

• passport:purge --expired --hours=744 deletes tokens and authorization codes once they expired more than 31 days ago, revoked or not. Revoked access tokens are kept that long on purpose: a refresh token is found through its access token when access is revoked, so an access token has to outlive its refresh token’s 30-day lifetime.
• oauth:revoke-ineligible marks revoked every personal access token, connection and service client its holder can no longer use: a deactivated or deleted account, or a person who lost CreatePersonalAccessTokens or UseMcp. A feature that is turned off isn’t a reason: its credentials wait for it to be turned back on. The API already refuses all of them on every request; this makes the Account and Administration pages say so. Each is revoked through its action, so it appears in the holder’s audit history.
• mcp:prune-clients deletes self-registered MCP clients nobody connected within a day and revokes those nobody has used for 90 days.
• model:prune deletes API request logs after API_REQUEST_LOG_RETENTION_DAYS (90).

The starter creates Passport’s personal access client the first time someone creates a personal access token. It needs no setup and isn’t listed with the applications.

When the Starter Refuses

Every rule for who may see, issue, change, revoke or use a credential is decided in one place, App\Domains\Api\CredentialAccess. Each action that issues, changes or revokes a credential takes the person acting and asks it, and so do the middleware that authenticates tokens, the consent screen and oauth:revoke-ineligible. To change a rule, change it there, and add a case to tests/Feature/Domains/Api/CredentialAccessTest.php. Pages, resources and actions ask it through the App\Domains\Api\Concerns\AuthorizesCredentials trait, which answers for the signed-in person: use it in your own pages too, rather than checking permissions, feature switches or impersonation yourself.

While Impersonating

An administrator impersonating someone acts with that person’s permissions, but can’t create, change or take away any credential: credentials only change under the name of the person changing them. The server refuses:

• creating or revoking the person’s personal access tokens;
• approving an application on the consent screen, or disconnecting one;
• creating, rotating, editing or revoking a service client, including creating an API user with one;
• registering, editing or revoking an application, regenerating its secret, or revoking an MCP client.

Changing the person’s preferences is refused too.

Administrators manage a person’s tokens and connections from the person’s page in Administration instead, where each action is recorded in the person’s audit history.

Under Environment Lockdown

Environment lockdown covers the consent screen: a person who can’t use the application can’t connect one to it either. Bearer requests to the API aren’t affected by lockdown.

With a Feature Off

• API_ENABLED=false makes every route under /api respond 404. Nobody can create a personal access token or connect an application (the consent screen answers 404), and /oauth/token refuses every grant to service clients and connected applications with unauthorized_client.
• MCP_ENABLED=false makes the MCP server, its discovery documents and dynamic registration respond 404, the consent screen answers 404 for MCP clients, and /oauth/token refuses to refresh their tokens.

Nothing is revoked when a feature is turned off. Turning it back on brings every credential back. Administrators can still see and revoke credentials of that kind in Administration, to shut a feature down cleanly, but can’t create or change them.

Behind a Proxy

A service client’s IP allowlist checks the address Laravel reports for the request ($request->ip()), and the starter trusts no proxy headers. When a load balancer or CDN sits in front of the application, configure trusted proxies ($middleware->trustProxies() in bootstrap/app.php) so Laravel reads the caller’s address from X-Forwarded-For; otherwise every request appears to come from the proxy.

When integrations come through Apigee, the application sees Apigee’s address, not the integration’s. Restrict callers in Apigee, or allowlist Apigee’s addresses on the client.

Error Responses

The REST API under /api answers errors as Problem Details (application/problem+json). Passport’s /oauth/* endpoints and the MCP server keep their own protocols’ error bodies, which OAuth and MCP clients expect.