The Cloudonix API.Core services are the backbone of all data management and access in the Cloudonix system. It maintains all the data models and offers authenticated APIs to perform business operations on the data as well as controlling different aspects of the behavior of the Cloudonix deployment.
Authentication and Authorization
The authentication behavior is designed for administration and provisioning UIs, such as the Cloudonix Dashboard - it allows a user, known to the system, to authenticate and receive a user API key. For applications and subscribers there are different authorization APIs that can be used to gain access to the API.Core REST API.
Authentication is implemented using an OpenID Connect implicit1 client authentication. The administration UI application is responsible for completing the OpenID Connect flow and retrieving the OAuth 2.0 "access token" and "id token" and sending them to the API.Core authentication end-point for verification and authorization.
To gain authorized to access API.Core, an application calls the Authentication API to verify the authentication tokens and retrieve an API key. All other API calls (other than authentication) must be authorized by the caller using the API key, by submitting the API key "key id" as a bearer token2.
AS discussed above, once an application (whether a user agent, or an automated process) has an API key (whether it was received by a user agent through the authentication API or was provisioned in some other way), the application can use the API key to authorize calls to privileged APIs.
Cloudonix Voice Application Access
When the Cloudonix voice application runtime - APP.Core - executes application business logic, such application logic may need to access API.Core application-specific APIs. To authorize such access, APP.Core will automatically provision "application API keys" and submit them to the application as part of the application execution.
While all API.Core API calls (other than authentication) require authorization using API keys, different calls may require different privileges, or allow differently privileged called access to different data.
API.Core has the following privilege levels:
- System Administrator - a system administrator has access to all levels of the API and can manipulate any data made available through the API, without limitation. A system administrator can be identified by its user record having both the "tenant id" and "domain id" field set to null.
- Tenant Administrator - a tenant administrator has access to all APIs that deal with tenant data (or data relating to a specific tenant) for the specific tenant they are an administrator for, as set in the user record's "tenant id" field. Such users can edit most tenant specific data fields (some data fields are editable only to system administrators) and can read all tenant specific data fields. A tenant administrator can be identified by its user record having the "tenant id" field set to the ID of the tenant record they have administration rights on, and the "domain id" field set to null.
- Domain Administrator - a domain administrator has access to all APIs that deal with domain data (or data relating to a specific domain) for the specific domain they are an administrator for, as set in the user record's "domain id" field. Such users can edit most domain specific data fields (some data fields are editable only to tenant or system administrators) and can read all domain specific data fields. A domain administrator can be identified by its user record having the "domain id" field set to the ID of the domain record they have administration rights on, and the "tenant id" field set to the ID of the tenant record that owns the specified domain record.
- Application - an application has access to all APIs that deal with application data (or data relating to a specific application) for the specific application, as set in the API key's "application id" field. Such users can retrieve all application specific data fields, and edit some application specific data fields as per the Cloudonix application security model.
- Subscriber - a subscriber is a system end-user registered under a domain. Some subscriber-oriented Cloudonix operations, such as SIP or messaging may require a subscriber to be authorized or to have an API key generated for them. Such keys allow access only to specific subscriber-oriented API calls.
Authorization & Authentication REST API
Administration REST API
Call Control and Session Management REST API
The Cloudonix domain model is used to represent an application domain for a tenant. Subscrbers, calls and application can only interact in a single domain - to interact outside a domain a call must be routed through an outbound or inbound trunk.
The domain model has the following fields:
|Number||A numeric identifier of the tenant that this domain belongs to|
|String||The domain name for this domain. The name is unique across Cloudonix WeCloud or a Cloudonix YouCloud instance|
|Object||A set of metadata fields that an application has assigned to this call. Cloudonix allows a customer to configure certain behaviors of the Cloudonix platform in a domain-specific way, which is stored as properties on this object. See below for details|
|Boolean||Whether this domain is active or has been deactivated. Inactive domains cannot handle voice calls or most API calls|
|Number||A numeric identifier of the domain's default application|
|Application||An application object describing the domain's default application|
|Array(Alias)||An array of object describing the domain's aliases|
Domain Profile Properties
The following properties are recognized by Cloudonix when set in the domain's
|Number||The default ringing timeout for a call in this domain, unless overridden for a session, in seconds. Default: 60|
|String||A URL to receive Registration-Free™ incoming call notifications|
|String||An API key to be sent to the Registration-Free™ control end-point as an authorization bearer token|
|Boolean||Whether to allow calls from inbound trunks to be dialed back out through an outbound trunk. Default: false|
|Boolean||Whether to allow calls with no LCR plan to be routed automaticaly through an outbound trunk if the destination is not a subscriber. Default: true|
|Boolean||Whether to automatically send SIP 183 status ("|
The Cloudonix session model represents a call in the Cloudonix platform and is used throughout the Session Management APIs and is also used in the session status notification callback and sent to CDR end-points.
The session model has the following fields:
|Number||A numeric identifier of the domain in which this call was processed|
|Domain||A domain object describing the domain in which this call was processed|
|Number||A numeric identifier of the subscriber that either originated (for outgoing and app-to-app) ore received the call|
|String||The MSISDN of the destination of the call|
|String||The MSISDN of the source of the call|
|String||A textual description of the direction of the call. See below for details|
|String||The unique session identifier used to access session data through the API and SDKs|
|Number||The time limit enforced on the call, in seconds.|
|Object||A set of metadata fields that an application has assigned to this call|
|Number||The call start time (when the SIP session has started) in UNIX epoch milliseconds|
|Number||The time the call was connected in UNIX epoch milliseconds|
|Number||the time the call was disconnected in UNIX epoch milliseconds|
|String||A URL that will receive notification callbacks when the|
|Object||An LCR routing plan. See [the LCR specifications] for more details|
|String||The current status of the call. See below for details|
direction field can have one of the following values:
|The call was incoming from a trunk to a subscriber|
|The call was outgoing from a subscriber to a trunk|
|The call was between two subscribers|
|The call was originated by an application|
status field can have one of the following values:
|The session was just created, or the SIP call was just initiated|
|The destination of the call is ringing|
|The call is connected to a destination or an application has answered|
|The call has completed and it was answered before it has ended|
|The call has completed but it was not answered while ringing before the ringing timeout has expired|
|The call was rejected by the destination|
|The call was disconnected due to not enough credit|
|The call was cancelled by the caller|
|The call was cancelled by an application without providing a reason|
|The call was disconnected due to an error in the application or Cloudonix|