# Accessing the API

To call Cubu’s S2S API, follow these steps:

1. Create a **Registered Application** in Cubu.\
   A registered application represents the 3rd party application calling the API.
2. Use the registered application's client ID and client secret to generate an **access token**.
3. Use the access token when **calling API endpoints**.

## Creating a Registered Application <a href="#creating-a-registered-application" id="creating-a-registered-application"></a>

{% hint style="info" %}
Cubu allows you to create up to 5 registered applications in your organization.
{% endhint %}

* In Cubu, go to Admin tools > Settings > Registered applications
* Click on the **New App** button.
* Name your application and click on **Create**.
* You will get a client ID and client secret when the application is created.
* Take note of the `client secret`. **You will not be able to see this secret again after closing the dialog box.**

<figure><img src="/files/2tvDPytjy8fOnf1KV4NA" alt="" width="375"><figcaption></figcaption></figure>

Add roles on the application details page to enable the application to access specific APIs.

It is best practice to give each application the minimal permissions it requires.

<figure><img src="/files/FI700EwNfPdYsxU1SCib" alt=""><figcaption><p>Registered Application Details Page</p></figcaption></figure>

## Obtaining an Access Token <a href="#obtaining-an-access-token" id="obtaining-an-access-token"></a>

To obtain an access token, you will need to issue a POST request to the token endpoint:

`https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token`

The `tenantId` and a summary of the required parameters is available on the **Getting Started** tab of the registered application page.

&#x20;

Request data:

* **grant\_type**: “client\_credentials”
* **client\_id**: the client Id created by the registered application.
* **client\_secret**: the client secret you received when you created the registered application.
* **scope:** \<clientId>/.default

#### cURL <a href="#curl" id="curl"></a>

{% code overflow="wrap" %}

```sh
$ curl --location 'https://login.microsoftonline.com/<tenantId>/oauth2/v2.0/token' \       
  --form 'grant_type="client_credentials"' \ 
  --form 'client_id="<clientId>"' \ 
  --form 'client_secret="<clientSecret>"' \ 
  --form 'scope="<clientId>/.default"'
```

{% endcode %}

**Example:**

{% code overflow="wrap" %}

```bash
$ curl --location 'https://login.microsoftonline.com/9bd2e211-64a3-436f-958a-e606e5d1f44d/oauth2/v2.0/token' \
  --form 'grant_type="client_credentials"' \
  --form 'client_id="4f9521a4-0a0a-440e-9f54-e93fb3c214f9"' \
  --form 'client_secret="skb8Q~nNMipZKU~INeqjiCSECRETUW4oGdAu"' \
  --form 'scope="4f9521a3-0a0a-440e-9f54-e93fb3c214f9/.default"'
```

{% endcode %}

Response:

```json
{
    "token_type": "Bearer",
    "expires_in": 3599,
    "ext_expires_in": 3599,
    "access_token": "<accessToken>"
}
```

Note that the token expires after 1 hour, and you must generate it again.

**C# Example:**

```csharp
private async Task<string> GetS2SAccessTokenAsync()
{
    using var client = new HttpClient();

    using var content = new MultipartFormDataContent {
        { new StringContent("client_credentials"), "grant_type"},
        { new StringContent(_clientId), "client_id"},
        { new StringContent(_clientSecret), "client_secret"},
        { new StringContent(_scope), "scope"},
    };

    var responseMessage = await client.PostAsync(_tokenEndpoint, content);
    var responseBody = await responseMessage.Content.ReadAsStringAsync();

    if (!responseMessage.IsSuccessStatusCode)
        throw new Exception($"Get Token failed ({responseMessage.StatusCode})");

    var tokenData = JsonHelper.Deserialize<TokenResponse>(responseBody);

    return tokenData!.Access_token;
}
```

**The TokenData class**

```csharp
public class TokenResponse
{
    public string Token_type { get; set; }
    public int Expires_in { get; set; } = 0;
    public int Ext_expires_in { get; set; }
    public string Access_token { get; set; }
}
```

## Calling S2S API Endpoints <a href="#calling-s2s-api-endpoints" id="calling-s2s-api-endpoints"></a>

The **base URL** for Cubu’s S2S API is `https://s2s.api.app.cubu.com/<applicationId>/`

The application ID is available on the registered application’s **General** tab.

You must provide the access token as a **Bearer** token in the **Authorization** header of each API request.

#### Example:

The following request returns the specified customer record:

{% code overflow="wrap" %}

```bash
$ curl --location 'https://s2s.api.app.cubu.com/0a115e6a-56e8-4b12-a8d7-2d5fb91ca1dc/customers/9cf609f4-bdb8-48b6-9215-0692d33e0c9e' \
  --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJ...'
```

{% endcode %}


---

# 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.cubu.com/guides/s2s-api-guide/accessing-the-api.md?ask=<question>
```

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.