AuthKit for Platforms

If developers build and deploy applications on your platform, you can create and configure a WorkOS environment for each of those applications through the Platform API. Your user’s app gets a working sign-in and sign-up experience, backed by enterprise features like Single Sign-On and Directory Sync, before they write a line of auth code.

1. WorkOS issues your platform a set of client credentials.
2. Your platform exchanges those credentials for a short-lived access token.
3. When one of your users creates an app, your platform creates a WorkOS team for them and an environment for the app.
4. Your platform mints an environment-scoped API key and configures the environment: redirect URIs, allowed origins, and webhook endpoints.
5. You pass the environment’s client_id and API key into your user’s app as environment variables.

Your user never touches the WorkOS Dashboard to get started. They receive an email invitation to the team you created for them, and can sign in later to turn on Single Sign-On, add a custom domain, or change branding.

Platform

Your product, as WorkOS sees it. A platform holds the credentials used to call the Platform API and is authorized on every team it creates.

Team

The WorkOS account that owns your user’s WorkOS resources and billing. Your platform creates one team per user, and the user you name becomes its admin.

Environment

A single deployment of your user’s app, with its own client_id, API keys, users, and configuration. Creating a team also creates a default project holding a Staging and a Production environment. Your platform adds its own environments on top of those.

Provisioning requires credentials to different APIs:

The Platform API is how you manage teams at a meta level including team creation, environment creation and API key management. Once a team is setup for your customer, configuring an environment works with the same endpoints using an environment API key. This retains compatibility with existing SDKs.

The team belongs to your user, not to your platform. That has a few implications:

• Production environments require active billing on the team. Until a team admin adds a payment method in the WorkOS Dashboard, your platform can only create sandbox environments.
• A team admin can revoke your platform’s access. Revocation deletes every API key your platform created for that team, so the app’s requests start failing immediately. Treat a 404 from the Platform API as lost access rather than a transient failure, and surface it in your product instead of retrying.
• Your user can change anything you configured. Your provisioning code should be safe to re-run, not assume its settings are still in place.

• Provision your first environment walks through the full flow, from access token to a running app.
• The Platform API reference documents every endpoint, parameter, and error code.