3.1 Understanding the authentication flow🔗

Business Central’s API uses OAuth 2.0 for authentication. Here’s what happens when you call bc-authenticate!:

1. bcnav sends your client ID and secret to Microsoft’s authentication servers

2. Microsoft verifies the credentials and returns an access token

3. bcnav stores this token and includes it in all subsequent API requests

4. When the token expires (typically after an hour), bcnav handles refresh automatically

For this to work, you need credentials from an Azure AD app registration.

3.2 Creating an Azure AD app registration🔗

3.3 Finding your Business Central company ID🔗

BC’s API requires a company ID to know which company’s data you’re accessing. To find it:

1. Open Business Central in your browser

2. Use the search (Alt+Q) to open Companies

3. The company ID appears in the URL, or you can find it programmatically once authenticated

Alternatively, once you’re authenticated with bcnav, you can query the companies endpoint to list all available companies with their IDs.

3.4 Understanding Racket parameters🔗

bcnav uses Racket parameters for configuration. If you’re new to Racket, a parameter is like a thread-safe global variable with some nice properties:

• You can read the current value by calling it with no arguments: (current-bc-tenant)

• You can set a new value by calling it with one argument: (current-bc-tenant "my-tenant-id")

• You can temporarily change it with parameterize (the value reverts when the block exits)

bcnav provides these configuration parameters:

3.5 Storing credentials securely🔗

You should never put secrets directly in source files that might be committed to version control. Here are better approaches:

3.6 Authenticating with client credentials🔗

With configuration in place, authenticate with bc-authenticate!:

;; #lang racket

(require bcnav)

;; Configure (assuming environment variables are set)

(current-bc-tenant (getenv "BC_TENANT_ID"))

(current-bc-client-id (getenv "BC_CLIENT_ID"))

(current-bc-client-secret (getenv "BC_CLIENT_SECRET"))

(current-bc-company (getenv "BC_COMPANY_ID"))

;; Authenticate

(bc-authenticate!)

If successful, this returns a token struct and stores it in current-bc-token. If there’s a problem, you’ll get an error message explaining what went wrong.

3.7 Interactive authentication🔗

For scenarios where you want to authenticate as a specific user (rather than as a service), bcnav supports interactive authentication. This opens a browser window for the user to sign in.

First, add a redirect URI to your app registration:

1. In your app registration, go to Authentication

2. Click Add a platform

3. Select Mobile and desktop applications

4. Add this redirect URI: http://localhost:8080/oauth/authorization

5. Click Configure

Also add Delegated permissions (in addition to or instead of Application permissions) under API permissions.

Then use bc-authenticate/interactive!:

(bc-authenticate/interactive!)

Interactive authentication provides a refresh token, so bcnav can automatically refresh your session without requiring you to sign in again.

3.8 Checking authentication status🔗

You can check if you have a valid token:

(token-valid?)   ;; #t if authenticated and token not expired

(token-expired?) ;; #t if token has expired

If your token expires and you authenticated with bc-authenticate! (client credentials), you’ll need to call it again. If you used bc-authenticate/interactive!, bcnav will automatically refresh the token when needed.

3.9 Troubleshooting🔗

3.10 Next steps🔗

With authentication working, you’re ready to start querying data. Continue to Querying with OData to learn about bcnav’s query language.