Get an authorization URL

Generates an OAuth 2.0 authorization URL to authenticate a user with AuthKit or SSO.

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const authorizationUrl = workos.userManagement.getAuthorizationUrl({
  connectionId: 'conn_01E4ZCR3C56J083X43JQXF3JK5',
  clientId: 'client_123456789',
  redirectUri: 'https://your-app.com/callback',
  state: 'dj1kUXc0dzlXZ1hjUQ==',
});

https://api.workos.com/user_management/authorize?
response_type=code&
client_id=client_123456789&
redirect_uri=https://your-app.com/callback&
state=dj1kUXc0dzlXZ1hjUQ==&
connection_id=conn_01E4ZCR3C56J083X43JQXF3JK5

If you are using AuthKit, set the provider parameter to "authkit", which will generate an authorization URL for your AuthKit domain. AuthKit will take care of detecting the user’s authentication method, such as identifying whether they use Email + Password or Single Sign-On,and direct them to the corresponding login flow.

Otherwise, to generate an authorization URL for a WorkOS SSO connection, you’ll have to specify the user’s connection, organization, or OAuth provider as a parameter. These connection selectors are mutually exclusive, and exactly one must be provided. The generated URL automatically directs the user to their identity provider. Once the user authenticates with their identity provider, WorkOS then issues a redirect to your redirect URI to complete the sign-in flow.

In the OAuth 2.0 protocol, a redirect URI is the location that the user is redirected to once they have successfully authenticated with their identity provider.

When redirecting the user, WorkOS will generate an authorization code and pass it to your redirect URI as a code query parameter, your app will use this code to authenticate the user. Additionally, WorkOS can pass a state parameter back to your application that you may use to encode arbitrary information to restore your application state between the redirects.

https://your-app.com/callback?code=01E2RJ4C05B52KKZ8FSRDAP23J&state=dj1kUXc0dzlXZ1hjUQ==

You can use state to encode parameters like originating URL and query parameters. This is useful in a flow where unauthenticated users are automatically redirected to a login page. After successful sign in, users will be routed to your redirect URI callback route. From there you can extract the originating URL from state and redirect the user to their intended destination.

You’ll need to configure the allowed redirect URIs for your application in the Applications section of the WorkOS Dashboard. Open your application and go to the Redirects tab. Without a valid redirect URI, your users will be unable to sign in. Make sure that the redirect URI you use as a parameter to get the authorization URL matches one of the redirect URIs configured for the application.

Redirect URIs follow stricter requirements in production environments:

• HTTPS protocol is required in production environments
• HTTP and localhost are allowed in staging environments
• The sole exception is the use of http://127.0.0.1 in production environments to support native clients.

Wildcards

WorkOS supports using wildcard characters (*) in Redirect URIs to handle dynamic subdomains or variable ports during development.

Subdomains

The * symbol can be used as a wildcard for subdomains; however, it must be used in accordance with the following rules:

• The protocol of the URL must not be http: in production environments.
• The wildcard must be located in the subdomain furthest from the root domain (e.g., https://*.sub.example.com will work, but https://sub.*.example.com will not).
• The URL must not contain more than one wildcard.
• A wildcard character may be prefixed and/or suffixed (e.g., https://prefix-*-suffix.example.com).
• A wildcard will not match across multiple subdomain levels (e.g., https://*.example.com will not match https://sub1.sub2.example.com).
• Wildcards cannot be used with public suffix domains (e.g., https://*.ngrok-free.app will not work).
• The wildcard will match letters, digits, hyphens, and underscores.
• A URL with a wildcard cannot be set as the default redirect URI.

Ports

To support RFC 8252 (“OAuth 2.0 for Native Apps”) and local development, a wildcard may be used in place of the port number.

• This is strictly limited to localhost and loopback IP addresses (e.g., 127.0.0.1).
• Example: http://localhost:*/auth/callback is valid.

The Proof Key for Code Exchange (PKCE) flow is an extension to the OAuth 2.0 Authorization Code flow. It enables public clients, like native apps or single-page apps, to perform the authorization code flow securely. If you are developing a client that makes API calls in public, you’ll need to use this flow.

In this flow, your client generates a code verifier which is a high-entropy cryptographic random string. A code challenge is derived by hashing the code verifier. Instead of using a client secret, provide the code challenge when getting the authorization URL and the code verifier when authenticating a User.

If there is an issue generating an authorization URL, the API will return the original redirect URI with error and error_description query parameters. If provided, the state value will also be included.

https://your-app.com/callback?error=organization_invalid&error_description=No%20connection%20associated%20with%20organization&state=123456789

Possible error codes and the corresponding descriptions are listed below.