README_initializing.mustache

We strongly recommend you initialize the `{{appShortName}}Client` only once and then re-use it throughout your app, otherwise you will incur the cost of having to re-initialize multiple times or at every request, the cost of reduced connection pooling and re-use, and would be particularly costly in the client credentials flow, as that flow will be preformed on every request.

> The `{{appShortName}}Client` will by default retry API requests up to {{defaultMaxRetry}} times on 429 and 5xx errors.

#### No Credentials

```python
from {{packageName}} import ClientConfiguration, OpenFgaClient


async def main():
    configuration = ClientConfiguration(
        api_url=FGA_API_URL,  # required
        store_id=FGA_STORE_ID,  # optional, not needed when calling `CreateStore` or `ListStores`
        authorization_model_id=FGA_MODEL_ID,  # Optional, can be overridden per request
    )
    # Enter a context with an instance of the OpenFgaClient
    async with OpenFgaClient(configuration) as fga_client:
        api_response = await fga_client.read_authorization_models()
        await fga_client.close()
        return api_response
```

#### API Token

```python
from {{packageName}} import ClientConfiguration, OpenFgaClient
from {{packageName}}.credentials import CredentialConfiguration, Credentials


async def main():
    configuration = ClientConfiguration(
        api_url=FGA_API_URL,  # required
        store_id=FGA_STORE_ID,  # optional, not needed when calling `CreateStore` or `ListStores`
        authorization_model_id=FGA_MODEL_ID,  # Optional, can be overridden per request
        credentials=Credentials(
            method='api_token',
            configuration=CredentialConfiguration(
                api_token=FGA_API_TOKEN,
            )
        )
    )
    # Enter a context with an instance of the OpenFgaClient
    async with OpenFgaClient(configuration) as fga_client:
        api_response = await fga_client.read_authorization_models()
        await fga_client.close()
        return api_response
```

#### Client Credentials

```python
from {{packageName}} import ClientConfiguration, OpenFgaClient
from {{packageName}}.credentials import Credentials, CredentialConfiguration


async def main():
    configuration = ClientConfiguration(
        api_url=FGA_API_URL,  # required
        store_id=FGA_STORE_ID,  # optional, not needed when calling `CreateStore` or `ListStores`
        authorization_model_id=FGA_MODEL_ID,  # Optional, can be overridden per request
        credentials=Credentials(
            method='client_credentials',
            configuration=CredentialConfiguration(
                api_issuer=FGA_API_TOKEN_ISSUER,
                api_audience=FGA_API_AUDIENCE,
                client_id=FGA_CLIENT_ID,
                client_secret=FGA_CLIENT_SECRET,
            )
        )
    )
    # Enter a context with an instance of the OpenFgaClient
    async with OpenFgaClient(configuration) as fga_client:
        api_response = await fga_client.read_authorization_models()
        await fga_client.close()
        return api_response
```

### Custom Headers

#### Default Headers

You can configure default headers that will be sent with every request by passing them to the `ClientConfiguration`:

```python
from {{packageName}} import ClientConfiguration, OpenFgaClient


async def main():
    configuration = ClientConfiguration(
        api_url=FGA_API_URL,
        store_id=FGA_STORE_ID,
        authorization_model_id=FGA_MODEL_ID,
        headers={
            "X-Custom-Header": "default-value",
            "X-Request-Source": "my-app",
        },
    )

    async with OpenFgaClient(configuration) as fga_client:
        api_response = await fga_client.read_authorization_models()
        return api_response
```

#### Per-Request Headers

You can also send custom headers on a per-request basis by using the `options` parameter. Per-request headers will override any default headers with the same name.

```python
from {{packageName}} import ClientConfiguration, OpenFgaClient
from {{packageName}}.client.models import ClientCheckRequest


async def main():
    configuration = ClientConfiguration(
        api_url=FGA_API_URL,
        store_id=FGA_STORE_ID,
        authorization_model_id=FGA_MODEL_ID,
    )

    async with OpenFgaClient(configuration) as fga_client:
        # Add custom headers to a specific request
        result = await fga_client.check(
            body=ClientCheckRequest(
                user="user:anne",
                relation="viewer",
                object="document:roadmap",
            ),
            options={
                "headers": {
                    "X-Request-ID": "123e4567-e89b-12d3-a456-426614174000",
                    "X-Custom-Header": "custom-value",  # Overrides default header value
                }
            }
        )
        return result
```

#### Synchronous Client

To run outside of an async context, the project exports a synchronous client
from `openfga_sdk.sync` that supports all the credential types and calls,
without requiring async/await.

```python
from {{packageName}}.client import ClientConfiguration
from {{packageName}}.sync import OpenFgaClient


def main():
    configuration = ClientConfiguration(
        api_url=FGA_API_URL,  # required
        store_id=FGA_STORE_ID,  # optional, not needed when calling `CreateStore` or `ListStores`
        authorization_model_id=FGA_MODEL_ID,  # optional, can be overridden per request
    )
    # Enter a context with an instance of the OpenFgaClient
    with OpenFgaClient(configuration) as fga_client:
        api_response = fga_client.read_authorization_models()
        return api_response
```