> ## Documentation Index
> Fetch the complete documentation index at: https://help.lobyco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lobyco tenant authentication using client credentials flow

> Get an access token with the app registration Lobyco created for you, and send it with every API call.

In the Lobyco tenant setup, Lobyco registers the app that represents your service in its own Azure AD tenant and shares the credentials with you. There is nothing to set up in a directory on your side. This page is the token request your backend makes, and how it uses the token. The same request serves the [multi-tenant setup](/integration/get-started/api-authentication/multi-tenant-authentication-using-client-credentials-flow), with your own tenant id.

## Before you start

Ask Lobyco for the authentication configuration of the environment. You receive four values:

* `client_app_id`, the application id of the app that represents your service.
* `client_app_secret`, its secret. Store it as you store any production secret.
* `client_tenant_id`, the id of the tenant that issues the token.
* `lobyco_app_uri`, the application id URI of the Lobyco API, which becomes the token scope.

## The flow

<Steps>
  <Step>
    ### Request a token

    Send a `POST` to the token endpoint of the Microsoft identity platform, with the four values as form fields:

    ```http theme={"system"}
    POST /{client_tenant_id}/oauth2/v2.0/token HTTP/1.1
    Host: login.microsoftonline.com
    Content-Type: application/x-www-form-urlencoded

    client_id={client_app_id}
    &scope={lobyco_app_uri}.default
    &client_secret={client_app_secret}
    &grant_type=client_credentials
    ```

    The scope is always `{lobyco_app_uri}.default`, whatever roles the app has. A successful response carries the token and its lifetime in seconds:

    ```json theme={"system"}
    {
      "token_type": "Bearer",
      "expires_in": 3599,
      "ext_expires_in": 3599,
      "access_token": "{token}"
    }
    ```

    Lobyco recommends the [Microsoft Authentication Library (MSAL)](https://learn.microsoft.com/en-us/azure/active-directory/develop/scenario-daemon-acquire-token?tabs=dotnet#acquiretokenforclient-api) over the raw request, because it caches the token and renews it before it expires.
  </Step>

  <Step>
    ### Send the token with every call

    Put the token in the `Authorization` header of each request to a Lobyco API:

    ```http theme={"system"}
    Authorization: Bearer {token}
    ```

    A normal response from the first call, not `401 Unauthorized`, confirms the credentials. When the token expires, repeat the token request. There is no refresh token in the client credentials flow.
  </Step>
</Steps>

## Failure and edge cases

When a request is refused, check these first.

* **`401 Unauthorized` from a Lobyco API** means the token is missing, expired or issued for the wrong scope. Check the scope string first.
* **The token endpoint rejects the request** when the app id or the secret is wrong, or the secret has expired. Secrets have an expiry date; ask Lobyco for a new one before it passes.
* **Decode a token at [jwt.ms](https://jwt.ms/)** to see its claims when a call is refused: `aud`, `iss`, `exp` and `roles`.

## Related

* [Multi-tenant authentication using client credentials flow](/integration/get-started/api-authentication/multi-tenant-authentication-using-client-credentials-flow) — the same request with an app registered in your own tenant.
* [API authentication](/integration/get-started/api-authentication) — how to choose between the two setups, and the API key alternative.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.