# Build your first integration

Create a workspace key, discover the released API, and make your first call.

API keys are currently available to selected workspaces. [Contact Brigg](mailto:axel@brigg.no) to enable access.

## Create a workspace key

Open [API keys in Brigg](https://brigg.app/settings/developer) and choose your workspace's API keys. An owner or administrator creates a named key, such as **Reporting**, and selects its permissions. Start with read-only access to the apps your integration needs. Copy the secret once and store it in your server's secret manager.

Workspace keys act for the integration and remain active when their creator leaves. They access permitted shared workspace data. For an agent connection, [MCP](https://developer.brigg.app/mcp) supports both personal and workspace access.

## Discover available operations

The authenticated catalog includes your workspace's released app operations and the platform operations allowed by the key. Draft app definitions are not part of the public API.

```sh
export BRIGG_API_KEY='your_workspace_secret_key'

curl 'https://api.brigg.app/v1/operations' \
  -H "Authorization: Bearer $BRIGG_API_KEY"
```

The [List companies reference](https://developer.brigg.app/reference/customers/ListCompanies) explains filters, sorting and the returned Company record. You can also inspect the same schema programmatically:

```sh
curl 'https://api.brigg.app/v1/operations/customers.ListCompanies' \
  -H "Authorization: Bearer $BRIGG_API_KEY"
```

`customers.ListCompanies` requires read access to shared CRM companies. Choose an operation from your own catalog if your key has a different grant.

## Make a call

Send the operation's input object directly as the JSON request body. The response is the operation's output object directly. There are no top-level `input` or `output` wrappers.

```sh
curl 'https://api.brigg.app/v1/operations/customers.ListCompanies' \
  -H "Authorization: Bearer $BRIGG_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"limit":10}'
```

For a workspace with one matching company, the response looks like this (fictional data):

```json
{
  "items": [
    {
      "id": "e_company_example",
      "created_at": 1794301200000,
      "updated_at": 1794301200000,
      "created_by": "a_example",
      "private": false,
      "data": {
        "name": "Example Consulting",
        "industry": "konsulent",
        "website": "https://example.com"
      }
    }
  ]
}
```

Your workspace may return `{"items":[]}`. When `next_cursor` is present, pass it as `cursor` to continue with the same filters and sort. The `konsulent` industry value means consulting; API enum values stay stable across UI languages.

Queries like this one can be retried safely. Before your first create or update call, choose a stable `Idempotency-Key` and reuse it if the request needs a retry. See [retries and limits](https://developer.brigg.app/reliability).

## Generate a client or help an agent

Download your key's [workspace OpenAPI specification](https://api.brigg.app/v1/openapi.json) using the same authorization header. Its schemas describe the released operations visible to that credential. The [public platform specification](https://developer.brigg.app/openapi.json) contains platform contracts only.

Agents can read the [Markdown documentation index](https://developer.brigg.app/llms.txt), discover operations, inspect schemas, and invoke the same contracts through MCP. Never paste an API key into a chat transcript.