Laravel Passport Password Grant - Client authentication failed
When building an API for a mobile application using Laravel Passport, you often start with the standard authorization code flow. This works well if your app can handle redirects to a web server to obtain tokens. However, native mobile applications cannot easily perform browser-based redirects. In these scenarios, the Password Grant Type becomes the necessary alternative, allowing clients to authenticate directly against user credentials stored in the database.
Many developers encounter an immediate roadblock here: the invalid_client error. This is a standard OAuth2 response indicating that the server rejected the client's identity before it even processed the username and password. In Laravel Passport, this error specifically points to a failure in how the application verifies the client_id and client_secret.
The most common root cause stems from how Passport generates credentials versus how they are transmitted in requests. When you run php artisan passport:install, Laravel creates two types of clients for your API:
- Personal Access Client: Used for direct user-to-API authentication without a third-party client.
- Confidential Clients: Third-party applications that hold a
client_secret.
The password grant flow is strictly reserved for confidential clients. If you attempt to use the Personal Access Client credentials (which do not have a secret) with the Password Grant, or if you are using a Client ID generated via passport:client without explicitly checking its "Client Type," you will hit this wall.
To resolve the invalid_client error, you must ensure you are authenticating as a Confidential Client. Here is how to verify and configure this correctly:
Verifying Client Configuration
When generating clients using php artisan passport:client --personal, Laravel creates a client that lacks a client_secret. This is by design for security, but it breaks the Password Grant flow because the grant requires proof of identity via a secret. You must generate a non-personal client (often called a "Confidential" or "Standard" client) to support this flow.
If you are using Postman or a similar tool to send the request, ensure your payload targets a client that was created without the --personal flag. The request body should look like this:
{
"grant_type": "password",
"client_id": "3",
"client_secret": "8BUPCSyYEdsgtZFnD6bFG6eg7MKuuKJHLsdW0k6g",
"username": "test@gmail.com",
"password": "123456",
"scope": ""
}
If the error persists, double-check that you are using the client_secret associated with that specific ID. A frequent mistake involves copying the secret from a Personal Access Client or using an old secret from a different environment. The database table passport_client stores these secrets hashed; if the hash in your request logic doesn't match the stored hash, Passport rejects the connection immediately.
Implementing the Grant Logic
Even with valid credentials, you must ensure your Laravel application is configured to accept password grants. While the default routes handle authorization codes, the password grant route is distinct. You need a POST endpoint at /oauth/token that accepts the form data described above.
In older versions of Laravel or when using custom controllers, you might manually instantiate Passport::tokenFromRequest(). However, in modern setups (Laravel 5.4+), it is best to rely on the built-in Passport authorization controller or define a specific route that validates the credentials against the database.
The core logic relies on the Passport facade to verify the username and password. The system checks the users table for the matching email, retrieves the associated personal access token (if any), and then attempts to mint a new access token using the provided client credentials. If the client ID or secret does not match a record in the passport_client table, or if the user exists but has no password hash match (e.g., if you are logging in via API tokens instead of passwords), the error occurs.
Scope Considerations
Another subtle pitfall is the scope field. While an empty string works for broad access, some strict OAuth implementations expect a specific scope definition. If your client has scopes defined but you send an empty string or an undefined list, ensure that the client permissions allow the requested resource. However, the invalid_client error specifically relates to authentication, not authorization, so fixing the client credentials is the priority.
For robust implementation details and further troubleshooting on Laravel Passport configuration, resources like https://laravelcompany.com provide updated guides on handling OAuth flows in production environments. Understanding the distinction between personal and confidential clients is the key to unlocking the Password Grant flow for mobile apps.