You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Choreo is a powerful platform that enables developers to create, deploy, and consume services efficiently. The Choreo Developer Portal simplifies API discovery and usage, allowing developers to integrate APIs seamlessly into their applications.
6
+
7
+
This guide is intended for application developers (both internal and external) who wish to consume APIs published in the Developer Portal to build their applications. You will learn how to:
8
+
9
+
- Discover APIs
10
+
- Create an application and generate credentials
11
+
- Subscribe to an API
12
+
- Consume a published REST API via a web application
13
+
14
+
---
15
+
16
+
## Prerequisites
17
+
18
+
Before proceeding, ensure you have access to a published service to consume. If you do not have one, follow the [Develop a Service](../develop-components/develop-services/develop-a-service.md) guide to create and deploy a sample REST API.
19
+
20
+
---
21
+
22
+
## Discover APIs
23
+
24
+
In the Choreo Developer Portal, developers can search for APIs by name. APIs and services created and published through the Choreo Console are visible in the Developer Portal based on their visibility settings:
25
+
26
+
-**Public**: Visible to all users in the Developer Portal.
27
+
-**Private**: Accessible only to signed-in users.
28
+
-**Restricted**: Available to users with specific roles, enabling granular access control.
29
+
30
+
For more details, refer to [Control API Visibility](../api-management/control-api-visibility.md).
31
+
32
+
### Viewing Available APIs
33
+
34
+
The Developer Portal lists APIs categorized by their major versions. The API overview page displays:
35
+
36
+
- Subscribed versions of the API
37
+
- Subscription details (e.g., application name and creation date)
> **Tip:** It is recommended to use the latest version of an API. Copy the **Endpoint(s)** from the API overview page and integrate it into your client application to ensure compatibility with the most recent updates.
44
+
45
+
---
46
+
47
+
## Creating an API Key
48
+
49
+
To consume an API secured with an API Key, an API Key is required. To obtain an API Key, an application must first be created in the Choreo Developer Portal. This application represents a physical entity (such as a mobile app, web app, or device) and serves as the means to subscribe to APIs under a defined usage policy. The API Key is associated with a specific application, and an application can be created during the API Key generation process if needed.
50
+
51
+
---
52
+
53
+
### Steps to Create an API Key
54
+
55
+
1. Navigate to the [Choreo Developer Portal](https://devportal.choreo.dev) and sign in.
56
+
2. Click on **APIs** in the Developer Portal header.
57
+
3. Select the desired API that requires an API Key for access.
58
+
4. This will take you to the API overview page, where you can manage credentials.
59
+
60
+
#### Generating Environment-Specific API Keys.
61
+
62
+
Choreo allows you to generate API keys for production and non-production environments.
63
+
64
+
!!! note
65
+
Access to production endpoints may be restricted based on your user role. Ensure you have the required permissions before generating production keys.
66
+
67
+
Follow these steps to generate an API Key:
68
+
69
+
1. In the left navigation menu, select the desired environment under **Credentials**. The **API Keys** pane for the chosen environment will open.
70
+
2. If any API keys already exist, they will be listed here.
71
+
3. Click **Generate API Key** and configure the following options:
72
+
-**Key Name**: Provide a suitable name for the API key.
73
+
-**Environment**: Choose an environment (if multiple environments are configured for the API).
74
+
-**Application**: Select an existing application or create a new one.
75
+
-**Subscription Policy**: Choose an appropriate subscription policy.
76
+
4. Click **Generate**. The newly created API Key will be displayed.
77
+
78
+
79
+
!!! note
80
+
If the selected application is already subscribed to the chosen API, the subscription selection step will be skipped.
81
+
82
+
Use this API Key to authenticate API requests by including it in the `api-key` header when invoking the API.
@@ -42,129 +42,30 @@ The API overview page displays subscribed versions of the API along with subscri
42
42
43
43
{% include "create-a-subscription.md" %}
44
44
45
-
## Consume the API via your web application
45
+
## Consume an API
46
46
47
-
To securely invoke the API/service, you need to use your Identity Provider (IdP). Follow these steps:
47
+
You can generate a token to invoke the API.
48
48
49
-
1. Create a web application in Choreo.
50
-
2. Create an OAuth application in the IdP.
51
-
3. Configure the web application to authenticate API/service invocations using the IdP.
52
-
4. Deploy the web application.
49
+
1. If the API is secured by [OAuth2](https://wso2.com/choreo/docs/consuming-services/generate-an-access-token).
50
+
2. If the API is secured by [API key](https://wso2.com/choreo/docs/consuming-services/manage-api-keys)
53
51
54
-
For this guide, you’ll use:
55
-
-**WSO2 Asgardeo** as the IdP.
56
-
-**[choreo-samples/reading-list-app/reading-list-front-end](https://github.com/wso2/choreo-samples/tree/main/reading-list-app/reading-list-front-end)** as the web application. This is a React SPA that uses Axios to invoke the service. It is configured to work with the **[choreo-samples/reading-list-app/reading-list-service](https://github.com/wso2/choreo-samples/tree/main/reading-list-app/reading-list-service)**. You can modify this web application to work with your service or deploy the sample service in Choreo.
52
+
You can use the generated token to invoke the API
57
53
58
-
### Step 1: Create a web application component
54
+
=== "Access OAuth2 secured API"
59
55
60
-
!!! info
61
-
You can use your own web application instead of the sample. For this guide, you’ll use the [choreo-samples/reading-list-app/reading-list-front-end](https://github.com/wso2/choreo-samples/tree/main/reading-list-app/reading-list-front-end).
56
+
Use the access token as the Bearer token in the Authorization header.
62
57
63
-
To host the front-end application in Choreo, create a web application component:
64
-
65
-
1. In the Choreo Console, select the project for the reading list application from the project list in the header.
66
-
2. Click **Create** under the **Component Listing** section.
67
-
3. On the **Web Application** card, click **Create**.
68
-
4. Enter the following details:
69
-
70
-
|**Field**|**Value**|
71
-
|-----------------|-------------------------|
72
-
|**Name**|`Reading List Web App`|
73
-
|**Description**|`Frontend application for the reading list service`|
74
-
75
-
5. Click **Next**.
76
-
6. Click **Authorize with GitHub** to connect Choreo to your GitHub account.
77
-
7. In the **Connect Repository** pane, enter the following:
|**Build Command**|**`npm install && npm run build`**|
87
-
|**Build Output**|**`dist`**|
88
-
|**Node Version**|**`18`**|
89
-
90
-
8. Click **Create**. This initializes the service with the GitHub repository and takes you to the **Overview** page.
91
-
92
-
### Step 2: Create an OAuth application in the IdP
93
-
94
-
To invoke the API/service, you need an access token. Create an OAuth application in the IdP (for example, Asgardeo) with the following settings:
95
-
96
-
-**Allowed grant types**: Code
97
-
-**Public client**: Enable this option.
98
-
-**Authorized redirect URLs**: Add the web app URL.
99
-
-**Allowed origins**: Add the same URLs as authorized redirect URLs.
100
-
-**Access Token**: Set to JWT.
101
-
102
-
Choreo uses Asgardeo as the default IdP. When you create an application in the Choreo Developer Portal, it automatically creates a corresponding application in Asgardeo. Follow these steps to configure the Asgardeo OAuth application:
103
-
104
-
1. Sign in to [Asgardeo](https://console.asgardeo.io/) using the same credentials as Choreo.
105
-
2. Ensure you’re in the same organization used in the Choreo Developer Portal.
106
-
3. In the Asgardeo Console, click **Applications** in the left navigation. You’ll see the **readingListApp** created by Choreo.
107
-
4. Click the edit icon to edit the application.
108
-
5. Go to the **Protocol** tab and make the following changes:
109
-
1. Under **Allowed grant types**, select **Code**.
110
-
2. Select the **Public client** checkbox.
111
-
3. In **Authorized redirect URLs**, enter the web app URL and click **+** to add it.
112
-
4. In **Allowed origins**, add the same URLs.
113
-
5. Under **Access Token**, select **JWT** as the token type.
114
-
6. Click **Update**.
115
-
116
-
### Step 3: Configure the web application to connect to the IdP and invoke the service
117
-
118
-
Update the web app configurations to invoke the **Reading List Service** REST API. These configurations are environment-specific. For this guide, we’ll configure the development environment.
119
-
120
-
!!! note
121
-
The web app reads environment-specific configurations from the `window` object at runtime via the `config.js` file. You’ll mount this file for the development environment. Repeat this process for other environments as needed.
122
-
123
-
To configure the front-end application:
124
-
125
-
1. On the web application component page, click **DevOps** in the left menu, then click **Configs and Secrets**.
126
-
2. Click **+ Create**.
127
-
3. Select the following options and click **Next**:
To consume a published API secured with an API Key, you must generate an API Key specifically for that API. This API Key serves as a unique identifier, allowing authorized access while ensuring security and control over API consumption.
4
+
5
+
Once created, API Keys can be managed through two locations within the Choreo Developer Portal:
6
+
7
+
-**Credentials section of the API**: This section provides an overview of all API Keys associated with the specific API, enabling API owners to monitor and manage access.
8
+
-**Credentials section of the Application**: This section allows application owners to view and manage all API Keys linked to their application, ensuring they have control over API subscriptions and access.
9
+
10
+
From these sections, you can perform various API Key management actions, such as regenerating and deleting.
11
+
12
+
13
+
## API Key Regeneration
14
+
15
+
API Key regeneration allows you to obtain a new secret key for an existing API Key while ensuring minimal disruption to service. When an API Key is regenerated, a new secret key is generated, and the existing key remains valid for a grace period of one hour before being revoked. This ensures that applications have sufficient time to update their credentials without experiencing service interruptions.
16
+
17
+
!!! warning
18
+
Ensure that all applications using the existing API Key are updated with the newly generated key within the grace period to prevent any disruptions in API invocations.
19
+
20
+
## API Key Deletion
21
+
22
+
API Keys can be deleted when they are no longer needed. Deleting an API Key immediately revokes its access, preventing further use of the key for API invocations. This action is irreversible and should be performed with caution, as any application relying on the deleted API Key will lose access to the API immediately.
0 commit comments