Embed API Tools
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:
- [Recommended] Declare an embed filter in the instantiation of the Speakeasy SDK in your API handlers.
- 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-tokenendpoint areread-only. - Use the dashboard at
https://app.speakeasyapi.devto generate a temporary token. Once logged into the dashboard, select theEmbed Tokenslink from the navigation area on the left. On this page, there is a button labeledCreate 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>
<>
);
}