Standalone Connect

Standalone Connect allows applications with existing authentication systems to use AuthKit as their OAuth authorization server. Instead of migrating your entire authentication stack, you can leverage WorkOS’s OAuth infrastructure while keeping your existing user authentication as the source of truth.

Read more in the Standalone Connect guide.

Completes an external authentication flow and returns control to AuthKit. This endpoint is used with Standalone Connect to bridge your existing authentication system with the Connect OAuth API infrastructure.

After successfully authenticating a user in your application, calling this endpoint will:

• Create or update the user in AuthKit, using the given id as its external_id.
• Return a redirect_uri your application should redirect to in order for AuthKit to complete the flow

Users are automatically created or updated based on the id and email provided. If a user with the same id exists, their information is updated. Otherwise, a new user is created.

If you provide a new id with an email that already belongs to an existing user, the request will fail with an error as email addresses are unique to a user.

curl -X POST https://api.workos.com/authkit/oauth2/complete \
  -H "authorization: Bearer sk_example_123456789" \
  -H "content-type: application/json" \
  -d '{
    "external_auth_id": "ext_auth_01J3X4Y5Z6A7B8C9D0E1F2G3H4",
    "user": {
      "id": "user_12345",
      "email": "leroy.jenkins@example.com",
      "first_name": "Leroy",
      "last_name": "Jenkins",
      "metadata": {
        "department": "Engineering",
        "role": "Developer"
      }
    }
  }'

The user_consent_options can take an array of consent options that the user will be required to choose from on AuthKit’s OAuth consent screen. The chosen option will then become available as a JWT claim on the issued access token.

These options can be presented as either a flat or grouped set of options.

curl -X POST https://api.workos.com/authkit/oauth2/complete \
  -H "authorization: Bearer sk_example_123456789" \
  -H "content-type: application/json" \
  -d '{
    "external_auth_id": "ext_auth_01J3X4Y5Z6A7B8C9D0E1F2G3H4",
    "user": {
      "id": "user_12345",
      "email": "leroy.jenkins@example.com"
    },
    "user_consent_options": [
      {
        "claim": "urn:example:organization",
        "type": "enum",
        "label": "Organization",
        "choices": [
          { "value": "org_123", "label": "Acme Corp" },
          { "value": "org_456", "label": "Globex Inc" }
        ]
      }
    ]
  }'