BC Object Registry
API guide

Three steps from nothing to an issued range.

curl -H "X-API-Key: $BCOR_API_KEY" https://registry.example.com/api/v1/me

curl -H "X-API-Key: $BCOR_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -X POST https://registry.example.com/api/v1/ranges/allocate \
  -d '{"name":"Contoso Labels","size":20,"environments":["Production"]}'

{
  "range": { "from": 50120, "to": 50139 },
  "rangeText": "50120–50139",
  "idRanges": [{ "from": 50120, "to": 50139 }],
  "app": { "id": "…", "name": "Contoso Labels", "status": "Pending", "environments": ["Production"] }
}

• Send the key as X-API-Key: <key>, or as Authorization: Bearer <key>. Keys look like bcor_ab12cd34_….
• A key acts for its workspace. It never has more rights than the person who created it: if they leave the workspace or are blocked, the key stops working.

Members create and revoke their own keys; org admins see and revoke everyone's. Plans allow these active keys:

Object IDs only collide inside one Business Central tenant, so every PTE app belongs to a tenant.

All paths are under /api/v1. GET POST PATCH DELETE read allocate write

Issue a range

POST /ranges/allocateallocate

{ "name": "Contoso Labels", "size": 20, "bcTenantId": "…", "environments": ["Production"] }

• Optional: type (PTE default, or AppSource), tenantId, poolId (a specific pool, e.g. one of several AppSource pools).
• The app is saved as Pending. Add its App ID later with PATCH /apps/{id}.
• Two simultaneous requests never get overlapping ranges.

Check a range

POST /ranges/checkread

{ "from": 50100, "to": 50119 }

Returns free (true/false), the apps it would overlap, and the pool it falls in.

Register an app (CI)

POST /appswrite

{
  "name": "Warehouse Labels",
  "appId": "d1000001-0000-4000-8000-000000000001",
  "ranges": [{ "from": 50100, "to": 50119 }],
  "status": "Active",
  "repoName": "warehouse-labels",
  "environments": ["Production"]
}

Import

POST /import takes either apps (a JSON array shaped like POST /apps) or file ({ "name": "registry.json", "content": "…" }). Files can be your GitHub registry's registry.json or ObjectRegistry.md, an app.json, a CSV, or a .zip of repos sent with "encoding": "base64".

Commit body

{ "dryRun": false, "previewId": "…", "decisions": { "3": "update" } }

Errors use RFC 9457 problem details, Content-Type: application/problem+json:

{ "type": "about:blank", "title": "Tenant required", "status": 422, "detail": "Name the tenant with tenantId or bcTenantId…", "tenants": [ … ] }

Validation errors include errors: [{ "path": "size", "message": "…" }].

Per key, per minute.

Send Idempotency-Key: <unique string> (a UUID is ideal) on POST /ranges/allocate, POST /apps and POST /import commits. If a call times out and you retry with the same key, you get the first response back (with Idempotent-Replayed: true) instead of a second range.

The samples are in the repository under docs/api/samples/. Full listings are in the appendix.

var
    Registry: Codeunit "OBCF Object Registry Client";
begin
    Registry.SetApiKey(ApiKeyFromSetupPage);
    Message('Issued %1', Registry.IssueRange('Warehouse Labels', 20));
end;

$env:BCOR_API_KEY = "bcor_…"
./issue-range.ps1 -Name "Contoso Labels" -Size 20 -Environments Production

The real samples from docs/api/samples/, in full.

ALObjectRegistryClient.Codeunit.alBusiness Central client codeunit · lines 1–52

/// <summary>/// Calls the BC Object Registry API from Business Central (AL HttpClient)./// Issues a new object range for this tenant and environment, or checks one./// The API key lives in Isolated Storage (company-independent), never in code./// Pick an object ID from your own range; 50100 is only an example./// </summary>codeunit 50100 "OBCF Object Registry Client"{    Access = Public;     var        BaseUrlTxt: Label 'https://registry.onlybcfans.com/api/v1', Locked = true; // replace with your BC Object Registry address        ApiKeyStorageKeyTok: Label 'OBCF-ObjectRegistry-ApiKey', Locked = true;     procedure SetApiKey(ApiKey: SecretText)    begin        IsolatedStorage.Set(ApiKeyStorageKeyTok, ApiKey, DataScope::Module);    end;     /// <summary>Issue the next free range of Size IDs for ProjectName in this tenant, marked as deployed to this environment.</summary>    /// <returns>The range as text, e.g. "50120–50139".</returns>    procedure IssueRange(ProjectName: Text; Size: Integer): Text    var        AzureADTenant: Codeunit "Azure AD Tenant";        EnvironmentInformation: Codeunit "Environment Information";        Body: JsonObject;        Environments: JsonArray;        Response: JsonObject;        Token: JsonToken;    begin        Body.Add('name', ProjectName);        Body.Add('size', Size);        // Lands in the registry for this customer's tenant (Premium (Partner) has one per tenant).        Body.Add('bcTenantId', AzureADTenant.GetAadTenantId());        Environments.Add(EnvironmentInformation.GetEnvironmentName());        Body.Add('environments', Environments);         Response := Send('POST', '/ranges/allocate', Body, CreateGuid());        Response.Get('rangeText', Token);        exit(Token.AsValue().AsText());    end;     /// <summary>True when FromId..ToId is free in this tenant's registry.</summary>    procedure IsRangeFree(FromId: Integer; ToId: Integer): Boolean    var        AzureADTenant: Codeunit "Azure AD Tenant";        Body: JsonObject;        Response: JsonObject;        Token: JsonToken;    begin        Body.Add('from', FromId);        Body.Add('to', ToId);

Continued on the next page.

ALObjectRegistryClient.Codeunit.alcontinued · lines 53–95

        Body.Add('bcTenantId', AzureADTenant.GetAadTenantId());        Response := Send('POST', '/ranges/check', Body, CreateGuid());        Response.Get('free', Token);        exit(Token.AsValue().AsBoolean());    end;     local procedure Send(Method: Text; Path: Text; Body: JsonObject; IdempotencyKey: Guid) Result: JsonObject    var        Client: HttpClient;        Request: HttpRequestMessage;        Response: HttpResponseMessage;        Content: HttpContent;        Headers: HttpHeaders;        ApiKey: SecretText;        BodyText: Text;        ResponseText: Text;        ProblemErr: Label 'BC Object Registry returned %1: %2', Comment = '%1 = HTTP status, %2 = problem detail';        NoKeyErr: Label 'Set the BC Object Registry API key first (SetApiKey).';    begin        if not IsolatedStorage.Get(ApiKeyStorageKeyTok, DataScope::Module, ApiKey) then            Error(NoKeyErr);         Body.WriteTo(BodyText);        Content.WriteFrom(BodyText);        Content.GetHeaders(Headers);        Headers.Remove('Content-Type');        Headers.Add('Content-Type', 'application/json');         Request.Method := Method;        Request.SetRequestUri(BaseUrlTxt + Path);        Request.Content := Content;        Request.GetHeaders(Headers);        Headers.Add('X-API-Key', ApiKey);        // A retry with the same key returns the same range instead of issuing a second one.        Headers.Add('Idempotency-Key', Format(IdempotencyKey, 0, 4));         Client.Send(Request, Response);        Response.Content.ReadAs(ResponseText);        if not Response.IsSuccessStatusCode() then            Error(ProblemErr, Response.HttpStatusCode(), ResponseText);        Result.ReadFrom(ResponseText);    end;}

BC Object Registry

Questions or problems? Email info@onlybcfans.com.

BC Object Registry by OnlyBCFans. Not affiliated with Microsoft. Microsoft, Dynamics 365 and Business Central are trademarks of the Microsoft group of companies.

PowerShellissue-range.ps1Issue a range and write idRanges into app.json

# Issue a new object range with PowerShell 7 and write it into app.json.# Usage: ./issue-range.ps1 -Name "Contoso Labels" -Size 20 [-BcTenantId <guid>] [-Environments Production,UAT]param(  [Parameter(Mandatory)] [string] $Name,  [Parameter(Mandatory)] [int] $Size,  [string] $BcTenantId,  [string[]] $Environments = @(),  [string] $AppJson = "./app.json",  [string] $BaseUrl = $env:BCOR_URL ?? "https://registry.onlybcfans.com")$key = $env:BCOR_API_KEYif (-not $key) { throw "Set BCOR_API_KEY to an API key from the portal (API keys)." } $body = @{ name = $Name; size = $Size; environments = $Environments }if ($BcTenantId) { $body.bcTenantId = $BcTenantId } $result = Invoke-RestMethod -Method Post -Uri "$BaseUrl/api/v1/ranges/allocate" `  -Headers @{ "X-API-Key" = $key; "Idempotency-Key" = [guid]::NewGuid().ToString() } `  -ContentType "application/json" -Body ($body | ConvertTo-Json) Write-Host "Issued $($result.rangeText) for $Name"if (Test-Path $AppJson) {  $app = Get-Content $AppJson -Raw | ConvertFrom-Json  $app | Add-Member -NotePropertyName idRanges -NotePropertyValue $result.idRanges -Force  $app | ConvertTo-Json -Depth 20 | Set-Content $AppJson  Write-Host "Updated idRanges in $AppJson"}

VS Codevscode-tasks.jsonRun Task → Issue object range

// .vscode/tasks.json: "Run Task → Issue object range" asks for a name and size, then writes idRanges into app.json.// Needs PowerShell 7 and issue-range.ps1 next to app.json, with BCOR_API_KEY set in your environment.{  "version": "2.0.0",  "inputs": [    { "id": "name", "type": "promptString", "description": "Project name" },    { "id": "size", "type": "promptString", "description": "How many object IDs?", "default": "20" }  ],  "tasks": [    {      "label": "Issue object range",      "type": "shell",      "command": "pwsh",      "args": ["-File", "${workspaceFolder}/issue-range.ps1", "-Name", "${input:name}", "-Size", "${input:size}", "-AppJson", "${workspaceFolder}/app.json"],      "problemMatcher": []    }  ]}

curlcurl.sh/me, listing, issuing, checking, importing

#!/usr/bin/env bash# curl examples. Set BCOR_URL (e.g. https://registry.onlybcfans.com) and BCOR_API_KEY first.set -euo pipefailH=(-H "X-API-Key: ${BCOR_API_KEY}" -H "Content-Type: application/json") # Who am I (workspace, plan, scopes)curl -s "${H[@]}" "$BCOR_URL/api/v1/me" # List active PTE apps in one tenant (by BC Tenant ID)curl -s "${H[@]}" "$BCOR_URL/api/v1/apps?type=PTE&status=Active&bcTenantId=00000000-0000-0000-0000-000000000000" # Issue 20 IDs, marked as deployed to Production; safe to retry with the same Idempotency-Keycurl -s "${H[@]}" -H "Idempotency-Key: $(uuidgen)" -X POST "$BCOR_URL/api/v1/ranges/allocate" \  -d '{"name":"Contoso Labels","size":20,"environments":["Production"]}' # Is 50100–50119 free?curl -s "${H[@]}" -X POST "$BCOR_URL/api/v1/ranges/check" -d '{"from":50100,"to":50119}' # Import your GitHub registry.json (preview first, then commit with the previewId)curl -s "${H[@]}" -X POST "$BCOR_URL/api/v1/import" \  -d "$(jq -n --arg c "$(cat registry.json)" '{dryRun:true, file:{name:"registry.json", content:$c}}')"

GitHub Actionsgithub-actions-register-app.ymlRegister app.json on push to main

# .github/workflows/register-app.yml# On every push to main, register (or update) this repo's app.json in BC Object Registry.# Secrets: BCOR_API_KEY (write scope). Variables: BCOR_URL, BCOR_BC_TENANT_ID (Partner workspaces).name: Register app in BC Object Registryon:  push:    branches: [main]    paths: [app.json]jobs:  register:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v4      - name: Register or update the app        env:          BCOR_URL: ${{ vars.BCOR_URL }}          BCOR_API_KEY: ${{ secrets.BCOR_API_KEY }}          BCOR_BC_TENANT_ID: ${{ vars.BCOR_BC_TENANT_ID }}        run: |          set -euo pipefail          content=$(jq -c '.' app.json)          body=$(jq -n --arg c "$content" --arg t "${BCOR_BC_TENANT_ID:-}" --arg repo "${GITHUB_REPOSITORY#*/}" \            '{dryRun:false, file:{name:"app.json", content:$c}} + (if $t != "" then {bcTenantId:$t} else {} end)')          # Import keeps existing apps (duplicates are skipped by default); new apps are registered.          curl -sf -H "X-API-Key: $BCOR_API_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: $GITHUB_SHA" \            -X POST "$BCOR_URL/api/v1/import" -d "$body" | jq '.counts, .committed'