Skip to content

screen_hint parameter not working with getAuthorizationUrl() method #292

@pbucko1

Description

@pbucko1

Bug Description
The screen_hint parameter is not properly handled by the UserManagement::getAuthorizationUrl() method when trying to direct users to sign-up vs sign-in screens in AuthKit.

Expected Behavior
When using screen_hint: 'sign-up', users should be directed to the AuthKit registration screen.

Actual Behavior
The screen_hint parameter gets incorrectly encoded as connection_id[screen_hint] in the URL
This causes a WorkOS error: "Something went wrong - Couldn't sign in"
Users always see the sign-in screen regardless of the screen_hint value

Code Example - Not Working

use WorkOS\UserManagement;

// This doesn't work
$url = (new UserManagement)->getAuthorizationUrl(
    config('services.workos.redirect_url'),
    [
        'state' => $state = Str::random(20),
        'screen_hint' => 'sign-up'
    ],
    'authkit'
);

Generated URL (broken):
https://api.workos.com/user_management/authorize?client_id=xxx&response_type=code&redirect_uri=xxx&state=%7B%22state%22%3A%22xxx%22%7D&provider=authkit&connection_id%5Bscreen_hint%5D=sign-up

Workaround - Working

// Manual URL construction works
$params = [
    'client_id' => config('services.workos.client_id'),
    'response_type' => 'code',
    'redirect_uri' => config('services.workos.redirect_url'),
    'state' => $state,
    'provider' => 'authkit',
    'screen_hint' => 'sign-up'
];

$url = 'https://api.workos.com/user_management/authorize?' . http_build_query($params);

Generated URL (working):
https://api.workos.com/user_management/authorize?client_id=xxx&response_type=code&redirect_uri=xxx&state=xxx&provider=authkit&screen_hint=sign-up

WorkOS Package
name : workos/workos-php
descrip. : WorkOS PHP Library
keywords :
versions : * v4.26.0
released : 2025-06-23, last week
type : library
license : MIT License (MIT) (OSI approved) https://spdx.org/licenses/MIT.html#licenseText
homepage : https://workos.com
source : [git] https://github.com/workos/workos-php.git bb7b823
dist : [zip] https://api.github.com/repos/workos/workos-php/zipball/bb7b8233eb9fedd1d11365d2f1e51ec8a232620d bb7b823
names : workos/workos-php

Environment
PHP V: PHP 8.4.10 (cli) (built: Jul 4 2025 00:25:55) (NTS)
Laravel: v12.19.3

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions