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

# Brivo

> Connect Serval to Brivo Access so workflows can manage cardholders, credentials, and access groups through Brivo's OAuth API.

## About Brivo

Brivo Access is a cloud physical-access platform for cardholders, credentials, sites, and access groups. The Serval Brivo integration is in **Beta**. Each connection maps to one Brivo account in either the US (`access.brivo.com`) or EU (`access.eu.brivo.com`) environment.

**Authentication:** Customer-provided OAuth 2.0 application plus a Mashery API key. You create the application in Brivo Marketplace (authorization\_code and refresh\_token grants), paste the Client ID, Client Secret, and API key into Serval, and approve access in Brivo. Serval refreshes access tokens automatically. Brivo access tokens expire after five minutes, so refresh is required on nearly every call.

**Data sync:** On-demand only. Workflows call the Brivo Access API when they run. Four health checks verify accounts, users, access groups, and sites.

## What the Brivo integration enables

| Capability                | Description                                                                                                                              |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Workflow API access       | Workflows can call Brivo Access API operations on demand, covering accounts, users (cardholders), credentials, access groups, and sites. |
| User and group management | Create, update, and delete users; add or remove users from access groups; assign or unassign credentials.                                |
| Connection health checks  | Four automated checks verify account, user, access group, and site list access after connecting.                                         |

Anything defined in the [Brivo Access API](https://apidocs.brivo.com) can be reached through the generic request action. Auth headers are injected by Serval; do not put the API key or bearer token in workflow code.

## Get your credentials

<Steps>
  <Step title="Create a Marketplace application in Brivo Access">
    In [Brivo Access](https://access.brivo.com) (or [access.eu.brivo.com](https://access.eu.brivo.com) for EU accounts), open Marketplace and choose **Generate API Token**. Name the application, select the 3-legged / authorization\_code grant, and enable the refresh\_token grant. Password grant cannot be combined with authorization\_code.
  </Step>

  <Step title="Set the redirect URI">
    Add this redirect URI to the application: `https://svflow-auth-config.api.serval.com/brivo/oauth/callback`

    Self-hosted Serval deployments use `https://svflow-auth-config.api.<your-domain>/brivo/oauth/callback` instead. The connect dialog also shows the exact URI for your environment.
  </Step>

  <Step title="Copy the Client ID and Client Secret">
    Open the enabled application in Marketplace and copy both values.
  </Step>

  <Step title="Copy a Mashery API key">
    From [developer.brivo.com](https://developer.brivo.com/apps/mykeys), copy an API key for the same environment as the account (PROD vs EU). A `Developer Inactive` response usually means the key is missing, wrong, or for the other environment. Production keys are issued by Brivo; developer keys are capped at 25,000 calls per month.
  </Step>
</Steps>

<Warning>
  Treat the Client Secret and API key like passwords. Serval stores them to refresh tokens and to sign API calls, and only shows obfuscated values later.
</Warning>

## Connect in Serval

<Steps>
  <Step title="Open the Brivo connect form">
    Find Brivo in the Serval app catalog (it is labeled Beta) and start the connection.
  </Step>

  <Step title="Choose US or EU">
    Match the Brivo account: US uses `auth.brivo.com` and `api.brivo.com`; EU uses `auth.eu.brivo.com` and `api.eu.brivo.com`.
  </Step>

  <Step title="Paste Client ID, Client Secret, and API key">
    All three fields are required. Register the displayed redirect URI on the Brivo application before connecting.
  </Step>

  <Step title="Authorize in Brivo">
    Serval redirects to Brivo to sign in and approve access. Finish within 10 minutes of clicking Connect.
  </Step>
</Steps>

<Note>
  Brivo connections cannot be edited in place. To rotate the Client Secret or API key, reconnect and re-enter the values.
</Note>

## Verifying the connection

| Check              | What it verifies                |
| ------------------ | ------------------------------- |
| List Accounts      | Serval can list Brivo accounts. |
| List Users         | Serval can list cardholders.    |
| List Access Groups | Serval can list access groups.  |
| List Sites         | Serval can list sites.          |

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Custom HTTP integrations cannot refresh Brivo tokens">
    Brivo requires `grant_type=refresh_token` with Basic client credentials and the `api-key` header on `auth.brivo.com`. Custom integrations only offer API key, OAuth client credentials, or delegated OIDC, and cannot store a refresh token together with client credentials. Use this native integration instead.
  </Accordion>

  <Accordion title="'Developer Inactive' or 403 on API calls">
    The Mashery `api-key` header is missing or does not match the environment. Confirm the key from developer.brivo.com is for US or EU, matching the environment selected at connect time.
  </Accordion>

  <Accordion title="Brivo did not return a refresh token">
    The Marketplace application must include the `refresh_token` grant. Create a new application with authorization\_code and refresh\_token, then reconnect.
  </Accordion>

  <Accordion title="'Invalid or expired OAuth state'">
    Credentials entered in the connect dialog are held for 10 minutes. Start the flow again and finish Brivo approval promptly.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Brivo integration.