API key providers

Connect providers that authenticate with an API key instead of OAuth.

Overview

Some providers authenticate with a single opaque API key instead of OAuth. Pipes supports these as a first-class authentication method: your users provide their key, WorkOS stores it securely, and you retrieve it from your backend using the same flow you already use for OAuth access tokens.

Configuring an API key provider

Visit the Pipes section of the WorkOS Dashboard and click Connect provider, then choose the provider from the list. When adding a provider, you choose a single authentication method for the integration.

A provider is configured as either OAuth or API key – not both. This choice is made when you add the provider and can’t be changed afterward. If you need to switch a provider from one method to the other, remove it and add it again with the method you want.

When you choose API key, the only field you can set is an optional description, which is shown to your users in the widget to explain how your application will use their data.

The Pipes "Add provider" modal showing the OAuth/API key method choice, with API key selected.

Organization admins can enable or disable an API key provider for their own organization through organization-scoped providers. There are no credentials or scopes to override – the key is supplied per user when they connect.

Setting an API key

Users can set their key through the Pipes widget, which renders an API key entry form for any provider configured to use API keys. They paste their key and submit it; WorkOS stores the credential and the widget then shows the last four characters so they can confirm which key is connected and rotate it later.

Pipes widget showing the API key entry form for an API key provider

You can optionally set or rotate a user’s key from your backend with the upsert API key endpoint. The same endpoint handles both the initial install and subsequent rotations – supplying a new secret replaces the stored one.

JavaScript

 curl --request PUT \
  --url "https://api.workos.com/data-integrations/github/api-key" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "user_id": "user_01EHZNVPK3SFK441A1RGBFSHRT",
        "secret": "sk-1234567890abcdef"
    }
BODY

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

const workos = new WorkOS(process.env.WORKOS_API_KEY);

await workos.pipes.updateDataIntegrationApiKey({
  slug: 'github',
  userId: 'user_01EHZNVPK3SFK441A1RGBFSHRT',
  secret: 'sk-1234567890abcdef',
});

 require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.pipes.update_data_integration_api_key(
  slug: "github",
  user_id: "user_01EHZNVPK3SFK441A1RGBFSHRT",
  secret: "sk-1234567890abcdef"
)

 from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.pipes.update_data_integration_api_key(
    slug="github",
    user_id="user_01EHZNVPK3SFK441A1RGBFSHRT",
    secret="sk-1234567890abcdef",
)

 package main

import (
	"context"

	"github.com/workos/workos-go/v9"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Pipes().UpdateDataIntegrationAPIKey(context.Background(), "github", &workos.PipesUpdateDataIntegrationAPIKeyParams{
		UserID: "user_01EHZNVPK3SFK441A1RGBFSHRT",
		Secret: "sk-1234567890abcdef",
	})
	if err != nil {
		panic(err)
	}
}

 <?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->pipes()
    ->updateDataIntegrationApiKey(
        slug: "github",
        userId: "user_01EHZNVPK3SFK441A1RGBFSHRT",
        secret: "sk-1234567890abcdef",
    );

 import com.workos.WorkOS;
import com.workos.pipes.PipesApi.UpdateDataIntegrationApiKeyOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

UpdateDataIntegrationApiKeyOptions options =
    UpdateDataIntegrationApiKeyOptions.builder()
        .userId("user_01EHZNVPK3SFK441A1RGBFSHRT")
        .secret("sk-1234567890abcdef")
        .build();

workos.pipes.updateDataIntegrationApiKey("github", options);

 using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Pipes.UpdateDataIntegrationApiKeyAsync("github", new PipesUpdateDataIntegrationApiKeyOptions {
    UserId = "user_01EHZNVPK3SFK441A1RGBFSHRT",
    Secret = "sk-1234567890abcdef",
});

 use workos::Client;
use workos::pipes::UpdateDataIntegrationApiKeyParams;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .pipes()
        .update_data_integration_api_key(
            "github",
            UpdateDataIntegrationApiKeyParams {
                user_id: "user_01EHZNVPK3SFK441A1RGBFSHRT".into(),
                secret: "sk-1234567890abcdef".into(),
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}

Retrieving credentials

Once a user has connected an API key provider, fetch their credential from your backend with the vend credentials endpoint.

JavaScript

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

const workos = new WorkOS(process.env.WORKOS_API_KEY);

const result = await workos.pipes.createDataIntegrationCredential({
  slug: 'github',
  userId: 'user_01EHZNVPK3SFK441A1RGBFSHRT',
});

 {
  "active": true,
  "credential": {
    "object": "credential",
    "auth_method": "api_key",
    "value": "sk-1234567890abcdef"
  }
}

Providers Explore the third-party providers available for Pipes integrations

Up next