# Consuming an API (technical Implementation)
For API plans, with the information you find in the **Subscriptions** section, you can start implementing the necessary API calls in your application.
Use an API tool like [Postman](https://www.postman.com) or cURL-commands to try them out or to run a quick test.
{% hint style="warning" %}
The URL in the API calls **must always include** the **https\://** prefix, otherwise the API call will return a 404.
{% endhint %}
## Consuming a Service
To consume a service via the apinity marketplace, you need to have a Consumer Client for the authentication of your requests (Please refer to [Consumer Clients](/step-by-step/subscribe-and-consume-a-service/consumer-clients.md) for more information).
The first necessary step for the usage of every Service is the authentication to the API gateway. The gateway handles the authentication to the service provider automatically.
{% hint style="info" %}
The service provider may require additional authorization. In such case, API requests must carry two authorization tokens (one for the marketplace, and one for the provider). For more info, see the concept article about [Authorization](/concepts/authorization.md).
{% endhint %}
Depending on the authentication type, the connection can be established as described below.
### Connecting with API Key
Necessary for implementation are these two values:
* **Endpoint URL**: The Endpoint URL is the base URL for implementing every API Call. This is found in the **Technical Setup** of every subscribed API service under **Subscriptions**.
* **API Key**: The key is generated while creating a consumer client, and **can’t** be retrieved again after the consumer client has been saved. If you misplace it, you will need to generate a new key or create a new consumer client.
#### **Step 1: Login Call**
The first necessary API call is the `Login` needed for authentication against the apinity marketplace.
For this, use a `POST` to `https://api.marketplace.apinity.io/{EndpointURI}/login` with the following body as *raw JSON* request:
```
{"api-key": “API_KEY”}
```
{% hint style="info" %}
The key name in this JSON is always **api-key**, not the name of the consumer client.
{% endhint %}
**Example cURL:**
```
curl --location --request POST 'https://api.marketplace.apinity.io/hello-world/639041ec-a6ba-4684-b37e-10677d482eb7/login' \
--header 'Content-Type: application/json' \
--data-raw '{"api-key": "d2tzZW9rNmE5aGF4djNjYWVtZDhzb2hyNmZnZTpeWWdTdzJHRDNhI3BRRFVHT29jaF9tUjdkJHY="}'
```
If the Login Call is successful, you will receive a `200 OK` status response.
#### **Step 2: Extract access token from Login response**
In the **response** of this call, you will find the following information:
* `"expires_in": “expirationValue”` – Expiration time of the token in seconds
* `"access_token": "accessToken”` – The authorization token
**Example Response:**
```
{
"expires_in": 31536000,
"access_token": "Basic dnRsNnFpZXRqZG..."
}
```
{% hint style="info" %}
The access token has a lifetime of exactly one year. Subsequent login calls within this period will return the same token. After expiry, a new login call is required.
Ending a subscription also invalidates the token as soon as the subscription expires.
{% endhint %}
#### **Step 3: All further calls - input Authorization header in every header**
Now you are ready to implement all further calls specified in the Swagger documentation by the service provider. For all these calls, these authorization values you received from the Login call should be sent as **headers**:
* **`x-apx-authorization`**`: “accesstoken"` (**required**)
* `authorization: “providersAuthKey"` (optional)
**Example cURL**
```
curl --location --request GET 'https://api.marketplace.apinity.io/hello-world/639041ec-a6ba-4684-b37e-10677d482eb7/v0/hello' \
--header 'x-apx-authorization: Basic dnRsNnFpZXRqZG...' \
--header 'Content-Type: application/json'
```
***
### Connecting with OAuth2
Necessary for implementation are these three values:
* **Endpoint URL**: The Endpoint URL is the base URL for implementing every API call. This is found in the **Technical Setup** of every subscribed API service under **Subscriptions**.
* **Client Id**: This is generated together with the consumer client and is necessary for Authentication. You can look it up by clicking “edit” on the respective consumer client in the **Consumer Clients** section.
* **Client Secret:** The secret is generated together with the consumer client and **can’t** be retrieved again after the consumer client has been saved. If you misplace it, you will need to generate a new secret or create a new consumer client.
#### **Step 1: Login Call**
The first necessary API call is the `Login` needed for authentication against the apinity marketplace.
For this, use a `POST` to `https://api.marketplace.apinity.io/{EndpointURI}/login` with the following body as *x-www-form-urlencoded* request:
```
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=CLIENT_ID' \
--data-urlencode 'client_secret=CLIENT_SECRET'
```
**Example cURL:**
```
curl --location --request POST 'https://api.marketplace.apinity.io/hello-world/639041ec-a6ba-4684-b37e-10677d482eb7/login' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=7ajv2oqbzerjln2ydlf0j9raasmo' \
--data-urlencode 'client_secret=Y1NuQGpMKmFHeXhuN1FtSUJ2XjdDM0smRUlj' \
--data-urlencode 'grant_type=client_credentials'
```
If the Login call is successful, you will receive a `200 OK` status response.
#### **Step 2: Extract access token from Login response**
In the **response** of this call, you will find the following information:
* `"expires_in": expirationValue` – Expiration time of the OAuth token in seconds
* `"refresh_token_expires_in": refreshTokenExpiration` – Expiration time of the OAuth refresh token in seconds
* `"access_token": "accessToken”` The authorization token
* `"refresh_token": "refreshToken"` – The refresh token
**Example Response:**
#### **Step 3: All further calls - input Authorization header in every header**
Now you are ready to implement all further calls specified in the Swagger documentation by the service provider. For all these calls, the authorization information you received should be sent as **headers**:
* **`x-apx-authorization`**`: “bearerToken"` (**required**)
* `authorization: “providersAuthKey"` (optional)
**Example cURL**
```
curl -v --location --request GET 'https://api.marketplace.apinity.io/hello-world/639041ec-a6ba-4684-b37e-10677d482eb7/v0/hello' \
--header 'x-apx-authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJiNWdkTlRfYmZzSmVLUHhiUklQRGUzQnF5NWRQREU1REZfejZ4djVkdzFnIn0.eyJleHAiOjE2NzkwNjAyNTQsImlhdCI6MTY3OTA1OTk1NCwianRpIjoiMGU5OTZmNmEtYWM4NS00ZGRmLWE4OTEtMGFmMTM3ODgxMjgyIiwiaXNzIjoiaHR0cHM6Ly9hdXRoLmFwaW5pdHkuaW8vcmVhbG1zL3N5bmNpZXItbWFya2V0cGxhY2UtZW5naW5lIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImQwYjZlODRhLWNmMGItNGU4Yi05MzkzLWYxNzYyNTk5YWE1MyIsInR5cCI6IkJlYXJlciIsImF6cCI6Im1hcmtldHBsYWNlLWdhdGVrZWVwZXIiLCJzZXNzaW9uX3N0YXRlIjoiMTFmNDhjOTgtODhkNC00ODg3LThiMDYtM2M2ZTQ1NDNjMmZjIiwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6InByb2ZpbGUgZW1haWwiLCJzaWQiOiIxMWY0OGM5OC04OGQ0LTQ4ODctOGIwNi0zYzZlNDU0M2MyZmMiLCJlbmdpbmUtdXNlcm5hbWUiOiJha28xbGV0a254OGN3Mm44bmFzYTRjdmF6aHN0IiwiZW1haWxfdmVyaWZpZWQiOnRydWUsInBhcnRuZXItbmFtZSI6IkJhbGF6cyBDUyBUZXN0IiwiZW5naW5lLXBhc3N3b3JkIjoicWU1RlZVYTRMUHExIW5aKEx3aypLYnh5VCNKIiwicHJlZmVycmVkX3VzZXJuYW1lIjoiN2FqdjJvcWJ6ZXJqbG4yeWRsZjBqOXJhYXNtbyIsImVuZ2luZS1hdXRoLXR5cGUiOiJPQVVUSDIifQ.bO67OyNubiJHKWXeZ_VDh4a0pZZ0eep0V1uFssZP6nYyssZfH_qg6ed1jrgCl-heMQ7EyzoN4UuQlxXKXV_-N6g-ExhtMyDOIYpm9Hy6_DAF3-1AUM1mhodS38xwPA-H2eco5k8VqJTf5L99cpTuCvVGGg5wWvHEv5MlPOj_MpCrA8AvdhR6l2g4Pfjeh186k9qHFW0cwYTL54SDZX2iJOyCLiX0o0qyA6_jM3HKn_9m3MLGPyCNqDCqFTdOcbFkRGDlkd5Ib-6c-MkOb0CVa7AMtNW4_87a7dc_elnTj0_fzUVEVqOb1RMFT9eufkQgBzUdRe9Icb3EUaDT6RkfCg' \
--data-raw ''
```
**Refreshing an expired OAuth2 Token**
The OAuth2 tokens used by the marketplace expire after a while (time in seconds is specified in the /token endpoint response) and need to be refreshed by using the refresh token. Refreshing the token works by sending another `POST` request to the same endpoint:
**URL:** `https://api.marketplace.apinity.io/{EndpointURI}/login`
**Method:** `POST`
**Content Type:** `application/x-www-form-urlencoded`
**Form Data:**
```
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=Bearer ...' \
```
This request will return a response with a new access token and refresh token:
```
{
"access_token": "Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJiNWdkTlRfYmZzSmVLUHhiUklQRGUzQnF5NWRQREU1REZfejZ4djVkdzFnIn0.eyJleHAiOjE2NzA0MTMyOTAsImlhdCI6MTY3MDQxMjk5MCwianRpIjoiNGM0ZDBjZDctMDBhNC00NjdjLWI4NGYtMTRlZWYwNmFkZTM4IiwiaXNzIjoiaHR0cHM6Ly9hdXRoLmFwaW5pdHkuaW8vYXV0aC9yZWFsbXMvc3luY2llci1tYXJrZXRwbGFjZS1lbmdpbmUiLCJhdWQiOiJhY2NvdW50Iiwic3ViIjoiZDBiNmU4NGEtY2YwYi00ZThiLTkzOTMtZjE3NjI1OTlhYTUzIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoibWFya2V0cGxhY2UtZ2F0ZWtlZXBlciIsInNlc3Npb25fc3RhdGUiOiIxMmVkOWQ1NS01MTM1LTQzZWUtOTMxZC1iYjY3NWFkNWUyOWYiLCJhY3IiOiIxIiwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6InByb2ZpbGUgZW1haWwiLCJlbmdpbmUtdXNlcm5hbWUiOiJha28xbGV0a254OGN3Mm44bmFzYTRjdmF6aHN0IiwiZW1haWxfdmVyaWZpZWQiOnRydWUsInBhcnRuZXItbmFtZSI6IkJhbGF6cyBDUyBUZXN0IiwiZW5naW5lLXBhc3N3b3JkIjoicWU1RlZVYTRMUHExIW5aKEx3aypLYnh5VCNKIiwicHJlZmVycmVkX3VzZXJuYW1lIjoiN2FqdjJvcWJ6ZXJqbG4yeWRsZjBqOXJhYXNtbyIsImVuZ2luZS1hdXRoLXR5cGUiOiJPQVVUSDIifQ.G2Gx9sPgOsgXVtkBJ68f8U2VgV8FYXlMN0nUlF4eL_SohRtqrXq3yCzm0HD8xjAIBn6JyanqPf3RRemlkCl1mR_45jdspGZwe6rx1NB_LfktKDGYEpuj8bDuLYbnyqXZEUK-KA5LvfbUU3Ys69Fhl7pLqSenRLZelhL_ysVU0lMXonPkoGNRu4wTSqafF3tky4DC5lMwZ-qBfGnAIdi6MmEwFxQe2PlNquvtaCoueA5jVdtknXD75Gq8UL1zRNCtJ8o8LYvgI3dWt-e4URCLl7YpiCnTmdqxn0hOXQQM5c9mA6VXi-elKKcqT15bB0cR_QpOjBV7FjOwDlOC5SpL5g",
"refresh_token": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI5MGU2YWU5MS01YTRjLTQyZWEtOGZhNy03OTgyMDc2ZTEwYTIifQ.eyJleHAiOjE2NzA0MTQ3OTAsImlhdCI6MTY3MDQxMjk5MCwianRpIjoiNjM2M2Q1OTMtNmNlMS00ZWY0LTgyMzUtYWI4NjM0Y2QxZGVkIiwiaXNzIjoiaHR0cHM6Ly9hdXRoLmFwaW5pdHkuaW8vYXV0aC9yZWFsbXMvc3luY2llci1tYXJrZXRwbGFjZS1lbmdpbmUiLCJhdWQiOiJodHRwczovL2F1dGguYXBpbml0eS5pby9hdXRoL3JlYWxtcy9zeW5jaWVyLW1hcmtldHBsYWNlLWVuZ2luZSIsInN1YiI6ImQwYjZlODRhLWNmMGItNGU4Yi05MzkzLWYxNzYyNTk5YWE1MyIsInR5cCI6IlJlZnJlc2giLCJhenAiOiJtYXJrZXRwbGFjZS1nYXRla2VlcGVyIiwic2Vzc2lvbl9zdGF0ZSI6IjEyZWQ5ZDU1LTUxMzUtNDNlZS05MzFkLWJiNjc1YWQ1ZTI5ZiIsInNjb3BlIjoicHJvZmlsZSBlbWFpbCJ9.yEST66fJA0SSkl6mqHKVu9wsxk_I7asx1LkELxVuWfs",
"refresh_token_expires_in": 1800,
"expires_in": 300
}
```
## Testing a Service
#### Performance Test
For performance testing, we offer two helpful pieces of information in the response header of every call:
* `X-Kong-Upstream-Latency`: Value in ms
This value shows how long the service provider takes to handle the API call (\*1).
* `X-Kong-Proxy-Latency`: Value in ms
This value shows how long the marketplace engine / API Gateway takes to handle the API call (\*2).
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.apinity.io/step-by-step/subscribe-and-consume-a-service/consume-an-api-technical-implementation.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.