CLI Auth enables command-line applications to authenticate users through the web using the OAuth 2.0 Device Authorization Flow.
The CLI Auth flow involves two main endpoints:
Read more about CLI Auth here.
Initiates the CLI Auth flow by requesting a device code and verification URLs. This endpoint implements the OAuth 2.0 Device Authorization Flow (RFC 8628) and is designed for command-line applications or other devices with limited input capabilities.
curl -X POST 'https://api.workos.com/user_management/authorize/device' \ -d client_id=client_123456789
POST/user_managementParameters Returns Exchanges a device code for access and refresh tokens as part of the CLI Auth flow. This endpoint should be polled repeatedly until the user authorizes the request, declines it, or the device code expires.
curl -X POST 'https://api.workos.com/user_management/authenticate' \ -d 'grant_type=urn:ietf:params:oauth:grant-type:device_code' \ -d 'device_code=ETaHpDNhfxu0HyLhp6b8HGSh26NzYJSKw3TT6aS7HKKBhTyTD0zAW6ApTTolug0b' \ -d 'client_id=client_123456789'
POST/user_managementParameters Returns When polling the device code endpoint, you may receive various error responses before the user completes authorization or if authorization fails. These errors help your application understand the current state and take appropriate action.
Possible error codes and the corresponding descriptions are listed below.
| Error code | Description |
|---|---|
authorization_pending | The authorization request is still pending as the user hasn’t yet completed the user interaction flow. Continue polling at the specified interval. |
slow_down | The client is polling too frequently and should slow down. Increase your polling interval by at least 5 seconds and continue polling. |
access_denied | The user declined the authorization request. Stop polling and inform the user that authorization was denied. |
expired_token | The device code has expired (typically after 5 minutes). Stop polling and restart the authorization flow if needed. |
invalid_request | The request is missing a required parameter or includes an invalid parameter value. Check that grant_type, device_code, and client_id are provided and correct. |
invalid_client | Client authentication failed (e.g., unknown client, client authentication not included, or unsupported authentication method). |
invalid_grant | The provided device code is invalid, malformed, or has already been used. |
unsupported_grant_type | The grant type is not supported. Ensure you’re using urn:ietf:params:oauth:grant-type:device_code. |
All error responses are returned with a 400 status code and follow the OAuth 2.0 error response format. For example:
{ "error": "authorization_pending", "error_description": "The authorization request is still pending as the user hasn't yet completed the user interaction flow." }