SBC Connect API

Overview

The SBC Connect API (formerly Auth API) exposes the account, identity, and delegation surfaces behind BC Registries services. The endpoints documented here fall into three groups, each with a specific audience.

Partner Authentication

Partner apps sell their own products (e.g. birth or death certificates, court services) and use BC Registries as the underlying authentication and payment infrastructure. The runtime flow:

1. User signs in through BC Registries SSO. Your app receives the user's bearer token.
2. Look up the user's BC Registries accounts by calling GET /users/orgs with the bearer:

   Authorization: Bearer <user token>
   x-apikey: <your app API key>
   
   
   The response lists every account the user belongs to:

   { "orgs": [ { "id": 574, "name": "Acme Legal", ... }, ... ] }
   
3. Let the user select an account. Carry that account's id as the Account-Id header on all subsequent requests. A user may switch accounts mid-session; your app is responsible for updating Account-Id when they do.
4. Call BC Registries services (typically Pay) with the three headers:

   Account-Id: <selected account id>
   Authorization: Bearer <user token>
   x-apikey: <your app API key>
   
   
   Billing routes to the selected account. Revenue collected on your behalf is settled separately, outside the API surface.

Optionally, call GET /users/@me to fetch the signed-in user's profile (name, username, etc.) for display in your app.

Business Affiliations

Endpoints used by Business Registry to attach the businesses managed by a BC Registries account. A business can be affiliated to an account using one of three methods:

• Passcode
• Magic link
• Delegation

These endpoints are used to get the affiliations on an account. An Account-Linking-Key gives a vendor access to a linked firm's affiliations (see Account Linking).

Account Linking

Coming soon

What it is for

Many businesses are managed by a firm on their behalf. For example, a law firm manages its clients' companies in its BC Registries account. That firm may also use third-party software, such as a legal practice or filing application, to prepare and submit work for those businesses.

Account linking lets that software (the vendor) work on the businesses in the firm's BC Registries account without the firm sharing logins or adding the vendor as a team member. The firm approves the connection once, and BC Registries gives the vendor a linking key. The vendor sends that key with its API calls to view and file for the firm's businesses.

• The vendor only sees businesses affiliated with the firm's account.
• Fees for filings are charged to the vendor's account, not the firm's.
• The firm can see and remove the connection at any time.
• A firm can link with more than one vendor. Each vendor gets its own key, and the firm can manage each connection separately.

Who is involved

One-time setup (vendor)

1. Make sure your vendor account has an API key under Account Settings → Developer Access.
2. On the same page, add one or more Redirect URLs. These are the pages in your application that the firm user can return to after linking, for example one per environment or application. BC Registries only sends users back to URLs registered here.
   • Query strings are allowed on the return URL, so https://app.example.com/callback also accepts https://app.example.com/callback?ref=123.
   • A URL ending in /* accepts any path under it.

Linking a firm's account

1. Vendor: From your application, send the firm user to the BC Registries account linking page with your vendor account ID and your return URL (URL-encoded):

   https://<BC Registries account site>/vendor-linking?vendorAccountId=<your vendor account id>&returnUrl=<your registered redirect URL>
   
   
   The account site is account.bcregistry.gov.bc.ca in production and sandbox.account.bcregistry.gov.bc.ca in sandbox.
2. Firm account administrator or coordinator: Logs in to BC Registries and selects the account to link. Only accounts where they are an administrator or coordinator are listed. They can also create a new account at this point. If the firm has more than one BC Registries account, they need to repeat these steps from the vendor system for each account.
3. BC Registries: Creates the linking key and, after a short confirmation screen, sends the user back to your return URL with two parameters added:

   <your return URL>?linkingKey=<linking key>&accountId=<firm's account id>
   
   
   If the return URL is not registered, or linking fails for another reason, the user sees an error on BC Registries and is not sent back.
4. Vendor: Store the linkingKey against the firm's accountId. Treat it like a password. BC Registries does not show the key again, so if it is lost, the firm account administrator or coordinator must link again. If you work with several firms, you will have one key per firm.

Calling APIs on the firm's behalf (vendor)

Add the firm's linking key to your normal API requests:

Account-Id: <your vendor account id>
x-apikey: <your API key>
Account-Linking-Key: <linking key for that firm>

With these headers you can list the firm's businesses (GET /orgs/{firm account id}/affiliations) and use the Business API for those businesses in the same way as your own. Fees are charged to your vendor account.

A linking key only works for the vendor account it was issued to. Account-Id must be your own vendor account. Requests from any other account return 403 Forbidden.

After linking

• Expiry: A link is valid for 1 year. The firm's administrators and coordinators get email reminders 30 days and 7 days before it expires, and can renew it from their account during those last 30 days. Renewing adds one year to the current expiry date.
• Managing connections: Under Account Settings → Third-Party Connections, the firm can see every vendor it has linked, with the date added, who added it, and the expiry date. Administrators and coordinators can remove a connection at any time, or renew it in the last 30 days before it expires. They get an email whenever a connection is added, removed, about to expire, or has expired, and these changes also appear in the account's activity log.
• Linking again: If the firm user goes through the linking steps again for your vendor account, a new key replaces the old one.
• Invalid keys: Requests with an expired, removed, or replaced key return 403 Forbidden. Expiry and removal notices are sent to the firm, not the vendor, so a 403 is usually how you find out. Send the firm user through the linking steps again to get a new key.

View the API

View the definition and select a path to try it out. To submit a request you will need an API key and an account ID, which are obtained as part of completing an access request. To set your session API key, click on the top, right AUTHORIZE button and under API Key Auth enter your key value. Click on AUTHORIZE, then OK.

View the API

Date and Date Time Formats

API Version History

Additional Resources

Postman collection of these calls is included in the Business Registry postman collection.

Page History

Updates of note to this page are recorded here.