# API and integrations

> The Giov API for your servers and automation tools, with API keys and Read/Write permissions, plus every other way to connect Giov.

The Giov API lets your own servers and automation tools work with your workspace, with no one at the keyboard. For example:

- **Keep the CRM in sync with your product.** When someone signs up, upgrades or cancels, your backend creates or updates their contact, tags and fields.
- **Act on events in your business.** When an order ships, add a note to the customer's conversation or reply to them; when a payment fails, create a CRM task for the team.
- **Reporting.** A nightly job copies conversations, contacts and analytics into your data warehouse or BI tool.
- **No-code automation.** Zapier, Make and n8n call the API with a key.
- **Internal tools.** Show a customer's open conversations in your admin panel or a Slack bot.

To let an AI assistant such as Claude or Cursor work in Giov with you, use the [Giov MCP server](/docs/mcp) instead. Outbound event webhooks aren't available yet.

## API keys

Admins and developers create keys in **Settings → MCP & API → API keys**. Admins see and manage every key in the workspace; developers see and manage their own.

1. Choose **Create API key**, give it a name (for example "CRM sync") and choose how long it lasts: 30 days, 90 days, 1 year, or until you revoke it.
2. Choose **Read** and **Write** for each area it needs, as for a connected app. It starts as **Read only**.
3. Copy the key. It starts with `giov_sk_` and is shown once; Giov keeps only a hash of it.

Because a key is a long-lived secret, creating one needs a sign-in from the last 12 hours. If yours is older, Giov asks you to sign in again first.

A key acts as the person who created it, with the permissions you chose, and never more than their role allows: a developer's keys can't reach conversations, customers or the team. It stops working when it expires (if you gave it an expiry), when it's revoked, or when that person loses access: they're removed or disabled, reset their password, turn off two-factor authentication or sign out everywhere. If their role changes, the key keeps only what the new role allows. To replace a key, create the new one, switch your server to it, then revoke the old one. A workspace can have 50 active keys. The API needs the Pro plan or higher.

## Make a request

Send the key in the `Authorization` header to `https://api.giovchat.app/v1`, followed by the path of the task:

```bash title="Terminal" tab="List conversations"
curl https://api.giovchat.app/v1/conversations \
  -H "Authorization: Bearer $GIOV_API_KEY"
```

```bash title="Terminal" tab="Create a contact"
curl -X POST https://api.giovchat.app/v1/customers/crm/contacts \
  -H "Authorization: Bearer $GIOV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Jordan Lee", "email": "jordan@example.com"}'
```

```bash title="Terminal" tab="Add a CRM note"
curl -X POST https://api.giovchat.app/v1/customers/crm/contacts/CONTACT_ID/notes \
  -H "Authorization: Bearer $GIOV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body": "Upgraded to the annual plan."}'
```

Reads use `GET` with query values; changes send a JSON body. Responses are JSON. Fields that hold credentials, such as tokens and secrets, are always replaced with `[hidden by Copilot]`.

The full list of endpoints, with their inputs and the permission each needs (`x-giov-permission`), is in the [OpenAPI document](https://giovchat.app/openapi/giov-api.json). Import it into Postman, Insomnia or your code generator.

## Permissions

Each key has its own permissions: **Read** and/or **Write** for each area, exactly like a [connected app](/docs/mcp#permissions). Reading needs Read on the area, and any change needs Write. You choose them when you create the key and change them later from **Permissions** next to it. A request must also be allowed for the role of the person who created the key. An admin can take a permission away from someone else's key, but only its creator can give it more.

Some tasks are never available to API keys, whatever their permissions: account deletion, security settings, connected apps and API keys themselves, billing changes, data exports, inviting people or changing roles, channel and mailbox credentials, push keys, the widget's identity verification, GiovBot tools, Google Analytics, and the AI provider, data retention and GiovBot's on/off switch in workspace settings.

## Errors and limits

| Status | `error` | Meaning |
|---|---|---|
| 400 | `invalid_arguments` | An unknown query value, a body that isn't a JSON object, or a field the key can't change |
| 401 | `api_key_required`, `invalid_api_key` | No key, or a key that's wrong, revoked or expired, or whose creator lost access |
| 403 | `insufficient_scope` | The key lacks Read or Write on that area, or its creator's role doesn't allow it |
| 403 | `not_available` | API keys never run this task |
| 404 | `not_found` | There's no such endpoint, or no such record |
| 429 | `rate_limited` | More than 300 requests a minute with this key |
| 5xx | | Giov couldn't complete the request; try again |

Every error body is `{"error": "…", "message": "…"}`. Errors from the task itself, such as a validation error, keep their own status and code.

## Security

- **Server-side only.** Never put a key in a website, a mobile app or a public repository. Store it in your server's secrets.
- **Least privilege.** Give each integration its own key with only the areas it needs, and the shortest lifetime that works. Give a key that never expires only to a server you control, and revoke it when you stop using it.
- **Audited.** Creating and revoking keys, and every change made with one, are recorded in the audit log (`api_key.created`, `oauth.grant_revoked`, `oauth.app_action`).

## Other integrations

These are the other ways to integrate Giov:

| Integration | Direction | Plans | Docs |
|---|---|---|---|
| GiovBot custom tools | Giov calls your endpoint | Wherever GiovBot is available | [GiovBot](/docs/giovbot) |
| Giov Copilot connections | Giov calls your API or MCP server | Advanced | [Giov Copilot](/docs/copilot) |
| Single sign-on (OIDC, SAML 2.0) | Your identity provider signs your team in | Business, Advanced | Coming soon |
| SCIM 2.0 provisioning | Your identity provider manages operators | Business, Advanced | Coming soon |
| Visitor push keys | Giov notifies your app's users | All plans | [Mobile apps](/docs/mobile#push-credentials) |
| Widget JavaScript API | Your page controls the chat | All plans | [JavaScript API](/docs/widget/javascript-api) |
| Giov API | Your servers read and change your workspace | Pro and up | [This page](#api-keys) |
| Giov MCP server | Your AI tools read Giov docs and work in your workspace | Docs: anyone. Workspace: Pro and up | [MCP server](/docs/mcp) |

## GiovBot custom tools

A custom tool lets GiovBot look something up or take an action in your systems during a conversation, such as checking an order. A tool is either a webhook or a tool from your remote MCP server.

For a webhook tool, Giov sends an HTTPS request to your endpoint, signed so you can verify it came from Giov:

- Headers `x-giov-timestamp`, `x-giov-tenant`, `x-giov-conversation` and `x-giov-signature`.
- The signature is an HMAC-SHA256 with the tool's own signing secret, over the timestamp, method, URL and a hash of the body. Reject requests whose timestamp is more than 5 minutes off.
- Tools only reach public HTTPS endpoints, and only read with `GET` unless you allow writes.

Setup and the exact verification steps are in [GiovBot](/docs/giovbot).

## Giov Copilot connections

Copilot is an assistant inside your own SaaS or app that knows the signed-in user. It acts through connections you approve:

- **HTTP:** Copilot calls your API with the actions you define or import.
- **Remote MCP:** Giov acts as the MCP client and connects to your MCP server.
- **In the browser:** actions can also run in the user's browser session, through the widget.

See [Giov Copilot](/docs/copilot).

## Single sign-on and SCIM

On Business and Advanced, admins can set these up in **Settings → Security**:

- **OIDC SSO** and **SAML 2.0**, each optionally required for the whole workspace.
- **SCIM provisioning** (SCIM 2.0, Users only) with a bearer token you create and can rotate or revoke.

> [!NOTE]
> Step-by-step guides for SSO and SCIM are coming soon.

## Visitor push keys

To notify your app's users when your team or GiovBot replies, upload your own Apple (APNs) key and Firebase service account in **Settings → Chat widget → Push notifications**. Your app registers device tokens through the Giov mobile SDK. See [Mobile apps](/docs/mobile#push-credentials).

## Widget JavaScript API

On your website, `window.ChatWidget` opens and closes the chat, and the `giov:openchange` event tells you when it opens. Signed-in users are passed securely with `window.GiovChatSettings`. See [JavaScript API](/docs/widget/javascript-api) and [Identify visitors](/docs/widget/identify-visitors).