Introduction

This SecureCall Provisioning Integration Guide provides comprehensive instructions for using the BroadSource SecureCall APIs to manage SecureCall services efficiently.

Getting Started

To get started using the API, an admin account can be requested by emailing sales@broadsource.com.au. Upon approval, a system-generated email from securecallapi.cloud with a username and temporary password will be received.

Access to the Administration APIs allows exploration of each API, including input and output requirements. 

You can use the APIs against the platform using the username and temporary password.

Go to the Authentication menu option on the left-hand side, then press Get Token. This will take you to a login page. The first time you log in, it will ask you to choose a new password.

Once you have logged in successfully, you should now be able to call any of the APIs.

NOTE: If you refresh the page, you will need to log in again; it doesn’t store the tokens.

The best place to start is the API “get the organization for the logged-in user”. This will display the organization you belong to and any children's organizations. Once you have the ID, you can use it to create users, sub-organizations, groups, etc.

The following sections are intended to assist the administrator with navigating the various processes and configurations required to integrate a provisioning or portal application with the SecureCall provisioning and administration systems, ensuring full automation of SecureCall via API can be achieved.

Glossary

Organization

Configuration object in the SecureCall hierarchy.

Used to hold general settings, users, groups, telephony configuration, and payment gateway configuration.

Service Provider

The owner of the telephony platform that is using SecureCall.
This refers to the primary entity at the top of the organizational hierarchy responsible for the telephony platform, which is referred to in this document as SERVICE_PROVIDER.

Reseller

The layer between the Service provider and the Merchant organizations.

Typically, this will be the reseller of the service provider’s telephony services, who has a direct relationship with the end customer.

Merchant

The end customer of SecureCall. This will typically be the enterprise company name.

Site

A suborganization of the merchant. Often associated with a physical location.

Group

Used to hold a list of permissions to assign to users.

User

End-user of the SecureCall client or an administrator user, or both.

Product Readiness

The BroadSource SecureCall APIs are designed for use by a provisioning system or portal. Our Partners may also offer these APIs to their customers (merchants or resellers), enabling them to automate the management of SecureCall services.

The full API documentation can be found in the SecureCall platform OpenAPI specification.

The documentation page provides detailed information on all the APIs, including input and output requirements. The APIs on the platform can be used with the provided developer username and temporary password.

Authorization Token

To get a token, send a request to the SecureCall OAuth2 service.

POST https://auth.au.securecallapi.cloud/oauth2/token

Content-Type: application/x-www-form-urlencoded

Body:

client_id=<client_id>&client_secret=<client_secret>&grant_type=client_credentials&scope=<scope>

The <client_id>, <client_secret>, and <scope> will be supplied via other channels. To request them, contact your Broadsource Account Manager.

The token returned is valid for 1 day. There isn’t a refresh token in this authorization flow, so once the token expires, use the same call to get another. The token should be cached and used until it expires, the authorization server is rate-limited, and doesn’t support getting a token for each API call.

Once a token is obtained, send it with any API call as the Authorization header as a bearer token. For example: Authorization: Bearer <token>

Organization Hierarchy

The hierarchy of an organization's levels is:

• System
  • Service Provider
    • Reseller
      • Merchant
        • Site

Settings, telephony, and payment gateway configuration are inherited from ancestor organizations. If a setting is configured for an organization, it affects that organization and any descendants.

System level is called ‘SecureCall’ and is the root of the hierarchy. There is only one of them and owned by BroadSource.
Service Provider is the primary entity at the top of the organizational hierarchy, responsible for configuring the telephony platform would be configured.

Reseller is the intermediate layer between Service Providers and Merchants. If the Service Provider sells directly to Merchants or uses SecureCall internally, there will usually be a dummy Reseller set up used to fill that layer, i.e., “Service Provider Reseller”.

The merchant is the end customer company.

Site can be a physical site where the merchant users are located, or could be a logical grouping for telephony or payment gateway purposes. There could also just be a site with all the users.

Service Provider Provisioning Flow

If you are storing the SecureCall Organization ID in your provisioning or administration system, then this only needs to be done once when first setting up.

GET /organizations – this returns the organization summary for the logged-in user. The user will be a special user associated with the client credentials used to generate the token.

The organization ID returned from this call will be the root organization for the appropriate Service Provider. The x in the table above can be a number from 0 to 9 or a character from a to f. That could be stored in your provisioning or administration system, and then this call wouldn’t need to be made again.

Creating a Reseller

Create a new organization using the “create a new sub-org” API:

POST /organizations/:orgId where :orgId is the SP organization ID

The body would just need the name of the reseller:

{
“name”: “Reseller Business Name”
}

If a Reseller wants a SecureCall environment to play with/demo, then it would be best to create a merchant-level organization for them.

Creating a Customer Organization

Create A New Organization Using the “Create A New Sub-Org” API:

POST /organizations/:orgId where :orgId is the reseller’s organization ID
The body would just need the name of the merchant: 
{
"name": "<string>"
}

Add the Telephony Settings Using the “Update the Telephony Provider” API:

PATCH /organizations/:orgId/telephony where :org_id is the merchant’s organization ID

The body would look like this:

{
"provider": "bwks",
"xsi_password": "xsi_group_admin_password",
"xsi_username": "xsi_group_admin_username"
}

The XSI username and password should be of a customer group admin who has the right to handle XSI requests for all the users.

Create the Designated Payment Gateway User

This user is responsible for updating the payment gateway details once everything is configured and the customer wants to go live. It would be a customer admin or financial controller. If it is an admin, they can forward the one-time email to a financial controller or someone with access to their payment gateway credentials.

A special group with the correct permissions will be created for the SERVICE_PROVIDER, which can then be assigned to the user when they are created, or it could be done as an update later.

This user doesn’t have to be someone with a phone, but can be. It doesn’t have to be someone who will use SecureCall, but can be. They would be created at the merchant level by using the “create a new user” API.

POST /organizations/:orgId/users where :orgId is the merchant’s organization ID

The body would look like this:

{
"name": "<string>",
"email": "<email>",
"telephony": {
"user": "<string>",
},
"groups": [
"<group_id>"
]
}

Create Sites

Sites are created the same as Merchants, replacing the reseller organization ID in the “create sub-org” API with the merchant’s organization ID.

There can be an arbitrary number of sites based on customer needs.

POST /organizations/:orgId where :orgId is the merchant’s organization ID

The body would just need the name of the site:

{
"name": "<string>"
}

Create Users for The Customer Using the “Create A New User” API

POST /organizations/:orgId/users where :orgId is the site’s organization ID

The body would look like this:

{
"name": "<string>",
"email": "<email>",
"telephony": {
"user": "<string>",
}
}

The name is usually the full name of the end user. It isn’t used for anything except
display.

The email is the user’s email address. If it is the same as the BroadWorks username that would be used in XSI requests, then the “telephony” section doesn’t need to be added. If the email and XSI username differ, then the “telephony” section is added with “user” being the XSI username.

Validate the Telephony

The telephony configuration can be tested once it is configured and at least one user is created using the “validate the telephony credentials” API. Not all sites need to be tested; just one would be fine, as it is testing the customer group admin XSI credentials stored at the merchant level. It needs a user with an email or telephony->user configured to use as a test case, so it should be done at the site level where the users are.

GET /organizations/:orgId/telephony/validate where :org_id is the site’s organization ID

If a 200 is returned, then the XSI credentials were used with the first user’s email/telephony->user username to retrieve the number of calls for the user. The result of that call doesn’t matter as long as it was successful.

Configure Payment Gateway

By default, the SERVICE_PROVIDER will be configured with a dummy gateway that accepts test card values and allows the customer to test and experiment with the SecureCall functionality without doing real transactions. Because the SERVICE_PROVIDER is at the Service Provider level, all the resellers, merchants, and sites will inherit that gateway configuration.

At some point, once all the above is configured, the customer will want to enable the real payment gateway. This can be done by using the “send a one-time link to update the payment gateway securely” API:

PUT /organizations/:orgId/gateway/onetime where :org_id is the merchant’s organization ID

The body needs to look like this:

{
"user": "<uuid>"
}

Where user is the UUID of a designated user that has been created in the SecureCall system, who has access to the organization and has the “gateway: update” permission. This is the designated person with the group that was created in the Product Readiness chapter above.