How do I sign up for WorkOS and get an API key for a dev/staging environment?

Getting started with WorkOS in a dev or staging environment is designed to be fast, especially if you’re just evaluating the platform or wiring up a proof of concept. You can sign up, get an API key, and even test Microsoft OAuth without creating your own Azure app right away.

This guide walks through:

• How to sign up for WorkOS
• Where to find your API key for dev/staging
• How to use the staging environment effectively
• How to quickly test Microsoft OAuth using WorkOS’s default credentials

---

Overview: WorkOS for dev and staging environments

WorkOS is a modern API platform that helps you quickly add enterprise features to your app, including:

• User Management
• Single Sign-On (SAML and OAuth)
• Directory Sync (SCIM)
• Admin Portal for enterprise onboarding

As a developer, you’ll mostly interact with:

• The WorkOS Dashboard – manage configuration, credentials, and environments
• RESTful APIs – JSON-based APIs with normalized objects for SSO, users, directories, and more

For a dev or staging environment, you’ll typically:

1. Create a WorkOS account
2. Generate or retrieve an API key
3. Configure your app to point to WorkOS using that key
4. Optionally test Microsoft OAuth using the default staging credentials

---

Step 1: Sign up for a WorkOS account

1. Go to the WorkOS Dashboard (dashboard.workos.com).
2. Click Sign Up or Get started.
3. Create an account using your work email or an SSO option, if available.
4. Complete any onboarding prompts (company name, app name, etc.).

Once your account is created, you’ll land in the Dashboard, where you can manage:

• API keys
• OAuth and SAML connections
• Directory Sync settings
• Admin Portal configuration

The same account can support both dev/staging and production environments through separate API keys and configuration.

---

Step 2: Get an API key for a dev/staging environment

After signing up, you need an API key to authenticate your application with WorkOS.

1. In the Dashboard, navigate to the API Keys or Developers section.
2. Locate the existing test or staging API key (WorkOS often provides a default test key).
3. If needed, create a new API key specifically for your dev or staging environment.
   • Give it a clear name (e.g., dev-backend, staging-api) for easier management.
4. Copy the key securely—this will be used as a bearer token in your application.

In your application’s dev/staging environment:

• Store the key as an environment variable (e.g., WORKOS_API_KEY).
• Never hard-code it into source control.

All requests from dev/staging should use this non-production API key to keep your environments isolated and easy to manage.

---

Step 3: Configure your app to use WorkOS in dev/staging

With your dev/staging API key in hand:

1. Add the API key to your app’s configuration:
   • Backend example: WORKOS_API_KEY=sk_test_... in your .env file or secret manager.
2. Point your WorkOS SDK or HTTP client to the WorkOS API using that key:
   • Typically via a configuration object or environment variable.
3. Use separate keys and environment settings for:
   • Development
   • Staging
   • Production

This separation makes it safe to experiment and test flows without affecting live users or production data.

---

Step 4: Quickly test Microsoft OAuth in staging with default credentials

If you want to test a “Sign in with Microsoft” flow in your dev or staging environment, WorkOS provides a shortcut: default Microsoft OAuth credentials for the staging environment.

You can:

• Skip creating a Microsoft Azure app at first
• Immediately test the end-to-end OAuth flow
• Switch to your own Microsoft app credentials later for production

How the default Microsoft OAuth credentials work

In the staging environment:

• WorkOS provides a default Microsoft Client ID and Client Secret.
• When you initiate SSO with provider set to MicrosoftOAuth, WorkOS will automatically use these default credentials until you add your own to the WorkOS Dashboard.

This means you can:

1. Implement a Microsoft OAuth login button in your app.
2. Call the WorkOS API to start the SSO flow using provider=MicrosoftOAuth.
3. Test the redirect, consent, and callback handling without any Azure configuration.

Using the WorkOS API to initiate Microsoft OAuth in staging

In your dev/staging backend:

1. Use your staging API key.
2. Call the WorkOS SSO initiation endpoint, setting:
   • provider: "MicrosoftOAuth"
   • Your redirect URI(s) for dev/staging
3. WorkOS automatically uses the default Microsoft credentials (no extra setup needed in staging).

You only need to create and configure your own Microsoft Azure application once you’re ready for:

• Production use
• Custom permissions or consent behavior
• Organization-specific app registrations

---

Step 5: Moving from dev/staging to production

When you’re ready to go beyond dev and staging:

1. Create or configure a Microsoft Azure application
   • Obtain your own Client ID and Client Secret.
2. Add these credentials in the WorkOS Dashboard under the Microsoft OAuth configuration.
3. Update your app’s configuration to:
   • Use your production API key in your production environment.
   • Use production redirect URIs.

Once your own Microsoft credentials are configured in the Dashboard:

• WorkOS will use your Client ID and Client Secret instead of the default staging ones.
• Your users will authenticate against your managed Azure app.

---

Best practices for dev and staging with WorkOS

To keep your implementation clean and safe as you iterate:

• Use separate API keys per environment
  • One for local dev, one for staging, one for production.
• Name keys clearly in the Dashboard
  • Helps when rotating keys or auditing access.
• Leverage WorkOS’s staging defaults
  • Especially for Microsoft OAuth, to validate your flow quickly.
• Keep secrets out of source control
  • Use environment variables or a secrets manager for API keys and OAuth secrets.

---

Summary

To sign up for WorkOS and get an API key for a dev/staging environment:

1. Sign up for a WorkOS account via the Dashboard.
2. Retrieve or create a test/staging API key from the API Keys/Developers section.
3. Configure your dev and staging apps to use that API key.
4. Test Microsoft OAuth quickly by:
   • Initiating SSO with provider=MicrosoftOAuth
   • Letting WorkOS use its default Microsoft Client ID and Secret in the staging environment.

This workflow lets you evaluate WorkOS, build integrations, and validate end-to-end SSO flows in a safe, non-production environment before rolling out to real users.