<!-- llms.txt: https://workos.com/llms.txt -->
<!-- feedback.md: https://workos.com/docs/feedback.md -->

> Agents: if this page is wrong, missing a step, or its code fails, report it instead of working around it. `POST https://api.workos.com/feedback` with `Content-Type: application/json` and body `{"message":"Agent report: what you tried, what happened, client and model","pageUrl":"https://workos.com/docs/pipes/api-keys"}`. Ask the user once first. No auth. No secrets. Details: https://workos.com/docs/feedback.md

# API key providers

## 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. The same choice is offered
when you [add a custom provider](https://workos.com/docs/pipes/custom-providers#api-key-custom-providers),
so a provider that isn't in the catalog can authenticate with an API key too.

> **Note:** 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.](https://images.workoscdn.com/images/a53bc846-bc3e-411b-bdb9-990c6e650c2d.png?auto=format\&fit=clip\&q=50)

> Organization admins can enable or disable an API key provider for their own
> organization through [organization-scoped providers](https://workos.com/docs/pipes/organization-scoped-providers).
> There are no credentials or scopes to override—the key is supplied per user
> when they connect.

You can also declare an API key provider from your backend with the
[create data integration](https://workos.com/docs/reference/pipes/data-integration/create) endpoint by
setting `auth_methods` to `["api_key"]`. There are no shared credentials or
scopes to configure, since the key is supplied per user. Include the optional
`api_key` object to install a first user's key in the same request, or omit it
to declare the provider and let users connect their own keys later through the
widget.

The same `auth_methods` value composes with a `custom_provider` block, which
declares an API key provider that isn't in the catalog. See [API key custom
providers](https://workos.com/docs/pipes/custom-providers#api-key-custom-providers) for the request
shape and the fields such a provider rejects.

## Setting an API key

Users can set their key through the [Pipes widget](https://workos.com/docs/widgets/pipes), 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](https://images.workoscdn.com/images/aae36945-3ec1-478b-870a-bc401b7013ff.png?auto=format\&fit=clip\&q=50)

You can optionally set or rotate a user's key from your backend with the
[upsert API key](https://workos.com/docs/reference/pipes/connected-account/upsert-api-key) endpoint.
The same endpoint handles both the initial install and subsequent
rotations—supplying a new secret replaces the stored one.

:::code-group

```bash language="curl"
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
```

```js language="js"
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',
});
```

```rb language="ruby"
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"
)
```

```py language="python"
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",
)
```

```go language="go"
package main

import (
	"context"

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

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 language="php"
<?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",
    );
```

```java language="java"
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);
```

```cs language="dotnet"
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",
});
```

```rust language="rust"
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](https://workos.com/docs/reference/pipes/access-token/vend-credentials)
endpoint.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request POST \
  --url "https://api.workos.com/data-integrations/github/credentials" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "user_id": "user_01EHZNVPK3SFK441A1RGBFSHRT"
    }
BODY
```

```js language="js" title="Request" tab="1"
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',
});
```

```rb language="ruby" title="Request" tab="1"
require "workos"

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

WorkOS.client.pipes.create_data_integration_credential(
  slug: "github",
  user_id: "user_01EHZNVPK3SFK441A1RGBFSHRT"
)
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

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

client.pipes.create_data_integration_credential(
    slug="github", user_id="user_01EHZNVPK3SFK441A1RGBFSHRT"
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

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

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

	_, err := client.Pipes().CreateDataIntegrationCredential(context.Background(), "github", &workos.PipesCreateDataIntegrationCredentialParams{
		UserID: "user_01EHZNVPK3SFK441A1RGBFSHRT",
	})
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

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

$workos
    ->pipes()
    ->createDataIntegrationCredential(
        slug: "github",
        userId: "user_01EHZNVPK3SFK441A1RGBFSHRT",
    );
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;
import com.workos.pipes.PipesApi.CreateDataIntegrationCredentialOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

CreateDataIntegrationCredentialOptions options =
    CreateDataIntegrationCredentialOptions.builder()
        .userId("user_01EHZNVPK3SFK441A1RGBFSHRT")
        .build();

workos.pipes.createDataIntegrationCredential("github", options);
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

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

await client.Pipes.CreateDataIntegrationCredentialAsync("github", new PipesCreateDataIntegrationCredentialOptions {
    UserId = "user_01EHZNVPK3SFK441A1RGBFSHRT",
});
```

```rust language="rust" title="Request" tab="1"
use workos::Client;
use workos::pipes::CreateDataIntegrationCredentialParams;

#[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()
        .create_data_integration_credential(
            "github",
            CreateDataIntegrationCredentialParams {
                user_id: "user_01EHZNVPK3SFK441A1RGBFSHRT".into(),
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "active": true,
  "credential": {
    "object": "credential",
    "auth_method": "api_key",
    "value": "sk-1234567890abcdef",
    "config": {}
  }
}
```

:::