> For the complete documentation index, see [llms.txt](https://docs.cubu.com/guides/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cubu.com/guides/s2s-api-guide/accessing-the-api.md).

# 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 %}