BC Object
Registry

Maker guide · Copilot Studio agent tools

Connect to
Copilot Studio

About 15 minutes

For: makers who want a Copilot Studio agent to list apps, check ranges and issue new object ranges in BC Object Registry.

Time: about 15 minutes.

You need

a Copilot Studio license and maker rights in a Power Platform environment;
a BC Object Registry API key (portal → API keys);
the OpenAPI 2.0 file from https://registry.example.com/api/v1/swagger.json, where registry.example.com stands for your BC Object Registry address.

The setup in four steps

1Create an API keyBC Object RegistrySection 2

2Download swagger.jsonOpenAPI 2.0 fileSection 3

3Add the REST API toolCopilot StudioSections 4–5

4TestTest paneSection 6

ProductBC Object Registry

PublisherOnlyBCFans

SpecOpenAPI 2.0 (swagger.json)

BC Object Registry · Connect to Copilot Studio1

01

What the agent will be able to do

Each row becomes one tool in your agent. The prompts are the kind of thing people type in chat.

Tool	API operation	Example prompt
List apps	`ListApps` GET /apps	Which apps are Pending in Adatum's tenant?
Check a range	`CheckRange` POST /ranges/check	Is 50100 to 50119 free for Contoso?
Issue a new range	`AllocateRange` POST /ranges/allocate	Get me 20 object IDs for Contoso Labels in Production.
List tenantsOptional	`ListTenants`	Which customer tenants do we have?
Free rangesOptional	`GetFreeRanges`	What's free in Contoso's PTE pool?

i

Write operations (delete, import, tenant changes) are marked advanced in the spec. Leave them out of a chat agent unless you have a reason to add them.

02

Create an API key for the agent

Create the key

WhereBC Object RegistryAPI keys page

In BC Object Registry, open API keys→Create API key.
Name it Copilot Studio agent, and give it the scopes Read and Allocate only.
Copy the key. Each person who uses the agent enters a key when the agent first connects. You can create one key per person, or share a team key.

Who it acts as: the key acts with the rights of whoever created it. Revoke it on the API keys page to cut the agent off at once.

BC Object Registry · Connect to Copilot Studio2

03

Download the OpenAPI 2.0 file

Save swagger.json

WhereYour browser

Open https://registry.example.com/api/v1/swagger.json and save it as bc-object-registry.swagger.json.

Copilot Studio builds REST API tools from OpenAPI v2. It would convert a v3 file, but our 2.0 file is written for Power Platform: it has connector-friendly summaries, and marks advanced operations as such.

04

Add the REST API tool

i

These steps follow Microsoft's "Extend your agent with tools from a REST API (preview)" documentation (October 2026). Labels can change while the feature is in preview.

1

Open Add tool

WhereCopilot Studio · your agent

Open your agent →Overview→Tools→Add tool. Or go to the Tools tab and select Add a tool.

2

Choose REST API

WhereAdd tool

Select New tool→REST API.

3

Upload the file

WhereREST API wizard

Upload bc-object-registry.swagger.json, either by dragging it in or by browsing to it. Check the details, then select Next.

BC Object Registry · Connect to Copilot Studio3

04

4

Description

WhereREST API wizard

Replace the generated text with something the orchestrator can match, synonyms included:

Suggested description

Tracks Business Central (BC) object ID ranges for per-tenant extensions (PTE) and AppSource apps. Use it to list, find or look up apps and their object ranges; check whether an object ID range is free or overlaps another app; and issue, reserve, allocate or get a new collision-free object range for a new extension, optionally for a customer tenant and Business Central environments.

5

Solution

WhereREST API wizard

Solution: pick a custom solution, or leave it blank to have one created. Select Next.

6

Authentication

WhereREST API wizard

Authentication: choose API key and fill in:

API key fields · type exactly

Field	Value
Parameter label	`BC Object Registry API key`
Parameter name	`X-API-Key`
Parameter location	Header

Select Next.

Illustration · not a screenshot

Authentication

Authentication type

API key

Parameter label

BC Object Registry API key

Parameter name

X-API-Key

Parameter location

Header

BackNext

What to fill in: API key, the label, X-API-Key and Header. The real Copilot Studio screen looks different.

BC Object Registry · Connect to Copilot Studio4

04

7

Select and configure your tool

WhereREST API wizard

Select and configure your tool: add the tools from section 1 one at a time.

Keep the name (e.g. "Issue a new range"), or shorten it.
Give each one a clear Tool description. For example, for Issue a new range:

Tool description · Issue a new range

Reserves the next free block of object IDs of the requested size for a new Business Central extension and saves it as a Pending app. Use when someone asks for, reserves or needs new object IDs or an object range.

On Review your tool's parameters, make sure every input has a description. Most come from the spec. Then select Next.

8

Review and publish

WhereREST API wizard

Review your tool, then Next. Wait for it to publish.

9

Create the connection

WhereAdd tool · Connection

Select Create connection. Back on Add tool, filter by REST API, and for each new tool:

Select the tool.
Under Connection, select Create new connection, paste the API key, and select Create.
Select Add and configure.

BC Object Registry · Connect to Copilot Studio5

05

Tune the inputs

On each tool's settings in the agent:

Tool	Inputs
Issue a new range `AllocateRange`	`name` and `size` are required. Premium (Partner) workspaces must also name the tenant. Let the agent fill `bcTenantId` from the conversation, or set a fixed value for a single-customer agent. `environments` takes Business Central environment names, e.g. `Production`.
Check a range `CheckRange`	`from` and `to`, plus the tenant on Partner workspaces.
List apps `ListApps`	Leave the filters optional. The agent can pass `status`, `type`, `q` or the tenant.

→

Tip: in the agent's instructions, add:

Agent instruction

When issuing object ranges, always confirm the project name and number of IDs with the user first, then show the issued range and the idRanges JSON for app.json.

06

Test

In the Test pane:

Which apps are pending?the agent calls List apps with status = Pending.
Is 50100–50119 free?Check a range answers free or names the overlapping apps.
Get 20 object IDs for Contoso Labels in Production.the agent confirms, calls Issue a new range, and shows something like 50120–50139 and the idRanges JSON.
In the portalthe new app appears as Pending, and the Audit log shows "Issued a range".

BC Object Registry · Connect to Copilot Studio6

06

Illustration · not a screenshot

Test your agent

Get 20 object IDs for Contoso Labels in Production.

Project Contoso Labels, 20 object IDs, environment Production. Shall I issue it?

Yes.

Issue a new range

Issued 50120–50139 for Contoso Labels. For app.json:

"idRanges": [
  { "from": 50120, "to": 50139 }
]

Test 3 from section 6: the agent confirms first, calls Issue a new range, then shows the range and the idRanges JSON. Your agent's wording and the real Copilot Studio screen will differ.

07

Alternative: a Power Platform custom connector

If your organization standardizes on custom connectors:

1

In Power Apps or Power Automate, open Custom connectors→New custom connector→Import an OpenAPI file, and choose bc-object-registry.swagger.json.

2

Security: choose API Key, with parameter label BC Object Registry API key, parameter name X-API-Key, location Header.

3

Create connector, then Test GetWorkspace with a new connection.

4

In Copilot Studio, Add tool→Connector, then pick the connector's actions.

BC Object Registry · Connect to Copilot Studio7

08

Troubleshooting

Symptom	Fix
`401 Invalid API key`	The key was revoked or mistyped, or its creator left the workspace. Create a new key and update the connection
`403 Missing scope`	The key needs Allocate to issue ranges. Create a key with Read and Allocate
`422 Tenant required`	Partner workspace: the call must name the tenant (`bcTenantId` or `tenantId`). The error lists your tenants
`422 Unknown environment`	Use the Business Central environment names that the error lists
`429 Rate limit exceeded`	Too many calls a minute for the plan; wait for `Retry-After`
The agent never picks the tool	Make the tool and API descriptions more specific, with synonyms (issue, reserve, allocate, object IDs)

BC Object Registry

Questions or problems? Email info@onlybcfans.com.

BC Object Registry by OnlyBCFans. Not affiliated with Microsoft. Microsoft, Copilot Studio, Power Platform, Dynamics 365 and Business Central are trademarks of the Microsoft group of companies. Steps based on Microsoft Learn: Extend your agent with tools from a REST API (preview).

learn.microsoft.com/microsoft-copilot-studio/agent-extend-action-rest-api

BC Object Registry · Connect to Copilot Studio8

Connect toCopilot Studio

What the agent will be able to do

Create an API key for the agent

Create the key

Download the OpenAPI 2.0 file

Save swagger.json

Add the REST API tool

Open Add tool

Choose REST API

Upload the file

Description

Solution

Authentication

Select and configure your tool

Review and publish

Create the connection

Tune the inputs

Test

Alternative: a Power Platform custom connector

Troubleshooting

Connect to
Copilot Studio