---
title: "Connect to an agency"
method: POST
path: "/agency-connections"
tags: ["agency-connections"]
---

# Connect to an agency

`POST /agency-connections`

## Request

- Base URL: `https://api.bokio.se/v1`
- URL: `https://api.bokio.se/v1/agency-connections`
- Auth: one of:
  - OAuth 2
    - Authorization code: `/authorize`
    - Client credentials
    - Token URL: `/token` scopes: `agency-connections:write`
  - HTTP bearer

Connects the integration to an existing agency. Requires the integration to be
approved for machine to machine auth on the Agency API. Request on already
connected agencies will refresh scope to match the requested scope in client
credentials grant.

**Scope:** `agency-connections:write`

## Request body

- AgencyConnectionCreate
  - `agencyId` string, uuid, required: The Bokio identifier of an existing agency

## Response `200`

Existing connection updated

- AgencyConnection
  - `id` string, uuid, required: Informational connection identifier
  - `agencyId` string, uuid, required
  - `agencyName` string, required
  - `organizationNumber` string, nullable
  - `scopes` string[], required
  - `status` 'active' | 'disconnected', required
  - `connectedDatetime` string, date-time, required

## Other responses

- `201`: Agency connection created
- `400`: Invalid request
- `403`: The integration does not have an approved agency API client-credentials privilege
- `404`: Agency not found

---

[API](https://skmtc.dev/bokio/apis/agency-api.md) - [All operations](https://skmtc.dev/bokio/apis/agency-api/llms.txt) - [OpenAPI document](https://skmtc.dev/bokio/apis/agency-api/revisions/2ec5b299f1d5?raw)