How to use API Products

With Products created, how do you use them?

This guide explains how to discover, request access to, and use API Products in the Frends API Portal. Whether you're integrating APIs into your application or exploring what's available, this guide will walk you through the entire process from discovery to making your first API call.

Discovering API Products

The API Portal provides a catalog of all available API Products that you can browse to find the functionality you need. The products you see in the catalog depend on several factors including your organization's access control tags, the product's visibility settings, and whether you're logged in.

Public API Products are visible to everyone, even if you're not logged in to the portal. This allows you to explore available APIs and read their documentation before deciding to request access. Private API Products are only visible to organizations that have been specifically authorized through access control tags, creating a curated experience where you only see the products relevant to your organization.

Each API Product in the catalog displays its name, description, and relevant tags. You can use the search and filtering features to find products that match your needs based on keywords, categories, or functionality. Click on any product to view its detailed documentation, including information about available operations, authentication requirements, and usage examples.

Understanding Access Environments

API Products in the portal can be available in two different Environments: Production and Sandbox. Understanding the difference between these Environments is important when requesting and using access.

The Production Environment is where live API operations run against real data and systems. Access to the Production Environment is typically controlled to ensure that only authorized organizations can make production API calls. This Environment is intended for your live applications and integrations.

The Sandbox Environment provides a safe testing space where you can experiment with the API without affecting production data or systems. This Environment is perfect for learning how the API works, developing your integration, and testing your implementation before moving to production. Many API products make the sandbox freely available to encourage exploration and development.

Requesting Access to an API Product

When you find an API Product you want to use, the next step is requesting access. The process depends on whether the API Product requires approval and which Environments are available.

If an API Product has a Sandbox Environment enabled and you don't yet have access to it, the Sandbox typically becomes available immediately without requiring approval. This allows you to start testing and developing right away. You'll see the API operations in an interactive documentation view where you can make test calls directly from your browser.

For production access, many API Products require explicit approval from an administrator. When approval is required, you'll see a Request Product Access button on the API Product page. Click this button to submit your access request. The request is sent to the administrators who manage the API product, along with information about your organization.

Administrators receive a notification about your access request and can review it in their management interface. They can see which organization is requesting access and can choose to approve or decline the request. If your request is approved, an access token is automatically generated for your organization, granting you the ability to call the API operations in the approved Environment.

If your request is declined, you'll receive a notification. You may want to contact the API Product administrators to understand why access was declined and whether there are any requirements or conditions you need to meet before resubmitting your request.

Accessing Your Tokens

Once your access request is approved, you need to retrieve your access token to begin making API calls. Each API Product your organization has access to receives its own unique token. These tokens are securely stored and managed by the API Portal.

To find your tokens, navigate to your organization settings in the portal. There you'll find a list of all API Products your organization has access to, along with the associated tokens for each product. You can copy the token to use in your applications and integrations.

The organization settings also provide tools for managing your tokens. If you suspect a token has been compromised, you can revoke it to immediately prevent any further access using that token. You can also refresh a token to generate a new one, which is useful for rotating credentials as part of your security practices. When you revoke or refresh a token, any applications using the old token will need to be updated with the new token.

Testing and Using the API

Once you have access to an API Product, you can begin testing and using it directly from the portal. When you view an API Product that you have access to, you'll see a Get Started in Production button (or a similar button for sandbox access). Click this button to open an interactive API documentation interface.

This interface works similarly to Swagger or OpenAPI documentation viewers, showing you all available operations within the API Product. Each operation displays its parameters, request format, and response format. You can make test calls directly from this interface by filling in the required parameters and clicking the execute button.

The portal automatically includes your access token in the API calls you make from this interface, so you don't need to manually configure authentication headers when testing. This makes it easy to quickly verify that the API works as expected and to understand the request and response formats before implementing the integration in your own code.

When you're ready to integrate the API into your own application, you'll need to include your access token in the Authorization header of your HTTP requests. The exact format and any additional requirements are documented in the API Product's documentation. Copy your token from your organization settings and configure your application to include it in all API calls.

Understanding Token Scope

It's important to understand that each token is specific to both an organization and an API Product. If your organization has access to multiple API Products, you'll have a separate token for each one. Each token only grants access to the operations included in its associated API Product—you cannot use a token from one API Product to call operations from a different product.

This design ensures fine-grained access control and makes it easy to revoke access to specific API Products without affecting your organization's access to other products. It also means that if you're building applications that use multiple API Products, you'll need to manage and use the appropriate token for each product.

Managing Organization Access

If you're an administrator of your organization, you have additional capabilities for managing API Product access. You can view all pending access requests, see which products your organization currently has access to, and manage the tokens for all products from the organization settings.

You can also invite additional users to your organization so they can access the same API Products and tokens. This is useful when you have a team working on integrations, as all members of your organization share the same access and tokens. Any user in your organization can retrieve and use the tokens from the organization settings.

Best Practices

When working with API Products in the portal, follow these best practices to ensure secure and reliable integrations. Always start by testing in the Sandbox Environment before moving to Production. This allows you to develop and debug your integration without risk to production systems.

Keep your access tokens secure and treat them like passwords. Don't commit them to source control, share them publicly, or include them in client-side code. Use Environment Variables or secure configuration management to store tokens in your applications.

Regularly review your organization's access and tokens. If you're no longer using an API Product, consider revoking your access to maintain good security hygiene. If you're working on multiple projects or have multiple Environments, consider requesting separate organizations for each to keep tokens and access separated.

Finally, make sure to read the API Product's documentation thoroughly before integrating. Understanding rate limits, error handling, and best practices for each API will help you build more robust integrations and avoid common pitfalls.