Skip to main content

Embed Speakeasy Tools as React Components

tip

You can alternatively see our NPM package for the full list of supported Speakeasy developer portal embeds and instructions.

Installing Speakeasy Embeds

npm install @speakeasy-api/react-embeds
#or
yarn add @speakeasy-api/react-embeds

Using Speakeasy Embeds

To embed Speakeasy components in your application, the first step is making sure they are properly authenticated and filtered for the logged in customer. After which you will be able to easily add the component into your react app

Authenticating and Filtering your Components

To get Speakeasy components working correctly, you will need to generate an accessToken filtered to the correct subset of data. There are two ways to generate an accessToken:

  1. [Recommended] Declare an embed filter in the instantiation of the Speakeasy SDK in your API handlers.
  2. Make an API request from your React app, passing in the filter as an API parameter. note: Access tokens retrieved through the /v1/workspace/embed-access-token endpoint are read-only.
  3. Use the dashboard at https://app.speakeasyapi.dev to generate a temporary token. Once logged into the dashboard, select the Embed Tokens link from the navigation area on the left. On this page, there is a button labeled Create Access Token, which opens up this modal. Note that access tokens generated through the dashboard must be restricted to a single Customer ID.

Recommended Option: Create Filtered Access Token in SDK

Creating a filtered accessToken in the SDK is a language-specific activity. For the full range of supported languages, see our documentation. This instruction set will be in Go.

Step one: set up the Speakeasy SDK

​ Add the sdk to your api project according to the documentation. ​

// routes.go

func addPublicRoutes(r *mux.Router) {
r := mux.NewRouter()

speakeasySDK := speakeasy.New(speakeasy.Config {
APIKey: "YOUR API KEY HERE",
ApiID: "main_api",
VersionID: "1.0.0",
}
r.Use(speakeasySDK.Middleware)

// Your paths
}

Step Two: add auth endpoint

Embed tokens can provide access to only a subset of your data, if desired. This is useful for allowing each of your customers to use your embedded component to view only their own data or for restricting which apis, versions, or endpoints you'd like to expose in your embedded component. ​

// controller.go

func EmbedAuthHandler(w http.ResponseWriter, r *http.Request) {
ctrl := speakeasy.MiddlewareController(req)

// Use your existing authentication provider or logic for the embed access token.
customerID := auth.GetCustomerID(req)

accessToken, err := ctrl.GetSDKInstance().GetEmbedAccessToken(ctx, &embedaccesstoken.EmbedAccessTokenRequest{
Filters: []*embedaccesstoken.EmbedAccessTokenRequest_Filter{
{
Key: "customer_id",
Operator: "=",
Value: customerID,
},
},
})

w.WriteHeader(http.StatusOK)
if err := json.NewEncoder(w).Encode(EmbedResponse{AccessToken: accessToken}); err != nil {
// handle error
}
}

// models.go

type EmbedResponse struct {
AccessToken string `json:"access_token"`
}

// routes.go

func addPublicRoutes(r *mux.Router) {
r := mux.NewRouter()

speakeasySDK := speakeasy.New(speakeasy.Config {
APIKey: "YOUR API KEY HERE",
ApiID: "main_api",
VersionID: "1.0.0",
}
r.Use(speakeasySDK.Middleware)


r.Path("v1/auth/embed-token").Methods(http.MethodGet).HandlerFunc(EmbedAuthHandler)

// Your other paths
}

Step Three: Add the embed to your react application

export const DataView = () => {
const [embedToken, setEmbedToken] = useState(undefined);

// This function will call the handler that you defined in step two.
const getEmbedToken = useCallback(async () => {
const accessTokenResponse = await axios.get("https://my-api.dev/v1/auth/embed-token);
return accessTokenResponse.data.access_token;
}, []);

// Set the initial token
useEffect(() => {
getEmbedToken.then(token => setEmbedToken(token));
}, [])

return (
<div>
<h1>View your data</h1>
<ThemeContainer> // Optional, if you don't want to provide your own theming
<SpeakeasyRequestsComponent
accessToken={embedToken}
onRefetchAccessToken={getEmbedToken}
/>
</ThemeContainer>
</div>
)
}

Alternate Option: Create a Filtered Access Token in React

Step One: Create a filter object

Set the accessToken in your react code by configuring a SpeakeasyFilter object:

type SpeakeasyFilter = {
// Currently supported filter keys.
key: 'customer_id' | 'created_at';
operator: '=' | '<' | '>';
value: string;
}

customer_id should almost always be set in your filter to restrict data to a single customer, lest you unintentionally share another customer's data.

The filters you configure are then serialized as json into the filters query parameter in the API request you will make.

const filters = useMemo(() => {
const customerId = ""; // your customer id.
return {
filters: [{
key: "customer_id",
operator: "=",
value: customerId
}]
};
}), [];

Step 2: Pass the filter as a parameter into the API request

return (await axios.get("https://app.speakeasyapi.dev/v1/workspace/embed-access-token", {
headers: {
"x-api-key": "" // your api key
},
params: {
filters
}
})).data.access_token;
}, []);

Step 3: Set up accessToken refresh

Nest the GET request from step 2 in onRefetchAccessToken a callback function that triggers when the 'accessToken' expires

const onRefetchAccessToken = useCallback(async () => {
return (await axios.get("https://app.speakeasyapi.dev/v1/workspace/embed-access-token", {
headers: {
"x-api-key": "" // your api key
},
params: {
filters
}
})).data.access_token;
}, []);

useEffect(() => {
getAccessToken()
.then(access_token => setAccessToken(access_token))
}, []);

Put it all together for a full example of constructing a filters object and making an API request:

const App () => { 
const [accessToken, setAccessToken] = useState("");

const filters = useMemo(() => {
const customerId = ""; // your customer id.
return {
filters: [{
key: "customer_id",
operator: "=",
value: customerId
}]
};
}), [];

const onRefetchAccessToken = useCallback(async () => {
return (await axios.get("https://app.speakeasyapi.dev/v1/workspace/embed-access-token", {
headers: {
"x-api-key": "" // your api key
},
params: {
filters
}
})).data.access_token;
}, []);

useEffect(() => {
getAccessToken()
.then(access_token => setAccessToken(access_token))
}, []);

// return
}

Step 4: Add Components to Your App

After a filtered accessToken has been created, adding the react components to your app should be easy. Speakeasy components can be added directly into your react pages. The authentication props are passed directly into the embedded component. See the example below:

const SomeReactComponent = (props) => {

// logic

return (
<>
<YourComponent />
<SpeakeasyRequestsComponent
accessToken={myApiToken}
onRefetchAccessToken={myApiTokenRefreshFunc}
/>
</>
<YourOtherComponent />
)

If you have multiple components that are using the same access token, a SpeakeasyConfigure component can simplify the integration

const App = () => {

// authentication

return (
<>
<SpeakeasyConfigure
accessToken={myApiToken}
onRefetchAccessToken={amyApiTokenRefresh}
>
<ThemeContainer> // Optional, if you don't want to provide your own theming
<SpeakeasyApiComponent />
<SpeakeasyRequestsComponent />
</ThemeContainer>
</SpeakeasyConfigure>
<>
);
}