# Authentication

Authenticate a user with a specified authentication method.

### email-verification

## Authenticate with an email verification code

Authenticates a user with an unverified email and verifies their email address.

A user with an unverified email address won’t be able to authenticate right away. When they attempt to authenticate with their credentials, the API will return an [email verification required error](/reference/authkit/authentication-errors/email-verification-required-error) that contains a pending authentication token.

If the [email setting](/authkit/custom-emails) for email verification is enabled, WorkOS will automatically send a one-time email verification code to the user’s email address. If the email setting is not enabled, [retrieve the email verification code](/reference/authkit/email-verification/get) to send the email yourself. Use the pending authentication token from the error and the one-time code the user received to authenticate them and to complete the email verification process.

### code

## Authenticate with code

Authenticates a user using AuthKit, OAuth or an organization’s SSO connection.

AuthKit handles all authentication methods, however it is conceptually similar to a social login experience. Like OAuth and SSO, AuthKit returns you a code that you can exchange for an authenticated user. See [Integrating with AuthKit](/authkit).

### redirect-uri

### Redirect URI

In the [OAuth 2.0](/glossary/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](/reference/authkit/authentication/code). 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.

```url title="Redirect URI with query parameters"
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 via the [Redirects](https://dashboard.workos.com/redirects) page in the dashboard. 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 you have configured in the dashboard.

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. The `*` symbol can be used as a wildcard for subdomains; however, it must be used in accordance with the following rules in order to properly function.

- The wildcard **must** be located in a subdomain within the hostname component. For example, `http://*.com` will not work.
- The wildcard **must** be located in the subdomain which is furthest from the root domain. For example, `https://sub.*.example.com` will not work.
- The URL **must not** contain more than one wildcard. For example, `https://*.*.example.com` will not work.
- A wildcard character **may** be prefixed and/or suffixed with additional valid hostname characters. For example, `https://prefix-*-suffix.example.com` will work.
- A URL with a valid wildcard **will not** match a URL more than one subdomain level in place of the wildcard. For example, `https://*.example.com` will not work with `https://sub1.sub2.example.com`.
- In production environments, wildcards cannot be used with [public suffix domains](https://publicsuffix.org). For example, `https://*.ngrok-free.app` will not work.
- The wildcard will match a sequence of letters (`A` through `Z`, and `a` through `z` ); digits (`0` through `9`), hyphens (`-`), and underscores (`_`). For example, `https://user:secret@foo.example.com` will not work with `https://*.example.com`.
- A URL with a wildcard cannot be set as the default redirect URI.

### pkce

### PKCE

The [Proof Key for Code Exchange](https://datatracker.ietf.org/doc/html/rfc7636) (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](/reference/authkit/authentication/get-authorization-url) and the code verifier when [authenticating a User](/reference/authkit/authentication/code).

### get-authorization-url

## Get an authorization URL

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



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.

### error-codes

### Error codes

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.

```url title="Redirect URI with an error code"
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.

| Error code                      | Description                                                                                                                                                                                                                                                                                                                        |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `access_denied`                 | The identity provider denied user access to the client application or the user denied an OAuth authorization request at the identity provider.                                                                                                                                                                                     |
| `ambiguous_connection_selector` | A connection could not be uniquely identified using the provided connection selector (e.g., organization). This can occur when there are multiple SSO connections under the same organization. If you need multiple SSO connections for an organization, use the connection parameter to identify which connection to use for SSO. |
| `connection_invalid`            | There is no connection for the provided ID.                                                                                                                                                                                                                                                                                        |
| `connection_strategy_invalid`   | The provider has multiple strategies associated per environment.                                                                                                                                                                                                                                                                   |
| `connection_unlinked`           | The connection associated with the request is unlinked.                                                                                                                                                                                                                                                                            |
| `invalid_connection_selector`   | A valid connection selector query parameter must be provided in order to correctly determine the proper connection to return an authorization URL for. Valid connection selectors are either `connection`, `organization`, or `provider`.                                                                                          |
| `organization_invalid`          | There is no organization matching the provided ID.                                                                                                                                                                                                                                                                                 |
| `oauth_failed`                  | An OAuth authorization request failed for a user.                                                                                                                                                                                                                                                                                  |
| `server_error`                  | The SSO authentication failed for the user. More detailed errors and steps to resolve are available in the Sessions tab on the connection page in the WorkOS Dashboard.                                                                                                                                                            |

### Validate API key

Validate an API key and retrieve associated metadata.

## Validate API key

Validates an API key and returns its associated metadata if the key is valid. Your application's API uses this endpoint to authenticate incoming requests that include an API key.

The endpoint returns the complete API key object when validation succeeds, allowing you to access the key's permissions and owner information for authorization purposes. If the key is invalid, the endpoint returns `null` for the `api_key` field.

### API Keys