Skip to content

How to Call Brief Connect Web API Endpoints

Overview

This guide explains how to authenticate and make calls to the Brief Connect Web API endpoints. All API calls require authentication.

Before you start

Before calling the Brief Connect Web API endpoints, ensure you have:

  • The Brief Connect Web API endpoint URL for your environment. You can find this on the Web API Azure Resource overview page.
  • A tool for making API requests (e.g. Postman, cURL etc.)
  • Access to the details for Brief Connect Server Application registration (Entra ID) for the target environment.
  • Entra ID Application registration or Service Principal for authenticating requests to Brief Connect Web API endpoints

Register Entra ID Application to access Brief Connect Web API

Role required: Cloud Administrator

  1. Go to Azure Portal - Entra ID - App registrations page
  2. Find and open your Application registration that you want to register for accessing Brief Connect Web API endpoints
  3. Open Manage - API permissions page
  4. Add next permission:
  5. Select an API: Select tab APIs my organization uses
  6. Search for Brief Connect Server Application registration (use the actual display name of the application) in the list of the apps and select it
  7. Select Application Permissions - WebApi.FullControl
  8. Click on Add permissions button
  9. After the permission added, click on Grant admin consent for

Register Service Principal to access Brief Connect Web API

Role required: Cloud Administrator

  1. Update parameters in the header of the script below

Parameters: * briefConnectServerSPObjectId: Object ID obtained from Azure Portal - Microsoft Entra ID - Enterprise applications for Brief Connect Server Application Registration * servicePrincipalObjectId: Object ID obtained from Azure Portal - Microsoft Entra ID - Enterprise applications for the target service principal

# ----- PARAMETERS SECTION -----
# Update parameters in this section according to the instruction

$briefConnectServerSPObjectId = ""
$servicePrincipalObjectId = ""

# ----- END PARAMETERS SECTION -----

$webApiFullControlAppRoleId = az ad sp show --id $briefConnectServerSPObjectId --query "appRoles[?value=='WebApiFullControl'].id" -o tsv

az rest --method "POST" --headers "Content-type=application/json" `
     --url "https://graph.microsoft.com/v1.0/servicePrincipals/$($servicePrincipalObjectId)/appRoleAssignments" `
     --body "{'principalId': '$($servicePrincipalObjectId)', 'resourceId': '$($briefConnectServerSPObjectId)', 'appRoleId': '$($webApiFullControlAppRoleId)'}"
1. Open Azure Portal with Cloud Admin account, open Cloud Shell, switch it to PowerShell mode, if it's not 1. Paste the updated script and execute it. 1. Validation steps: 1. Go to Azure Portal - Microsoft Entra ID - Enterprise applications 1. Find the target service principal in the list and open it 1. Go to Security - Permissions page, and validate that WebApi.FullControl permission is available there under Admin Consent tab. 1. If it's not there, but in the User Consent tab only, then click on 'Grant admin consent for ' button.

Authenticate API Calls

You can authenticate your API calls to Brief Connect Web API by adding the Authorization header to your API request:

Authorization: Bearer your-access-token-here

Example cURL request:

curl -H "Authorization: Bearer your-access-token-here" https://your-api-endpoint/ContentTypes

Access token - Entra ID access token (Access tokens in the Microsoft identity platform - Microsoft identity platform | Microsoft Learn), with included application role registered in the previous steps, for example 'Brief Connect Server Application -
WebApi.FullControl'

Example method 1: Using an Entra ID (Azure AD) Bearer Access Token

  1. Obtain an access token from Entra ID (Azure AD) using your App registration credentials. You can use tools like curl, Postman, or Azure CLI to request a token. Example using curl:
curl -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "scope=BC_SERVER_APP_ID/.default" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token

The response will include an access_token field. You need to include the result access token in Authorization header to authenticate requests.