Authentication & Authorization

Pay Attention, Cloudonix API Keys are different!

Unlike other API driven platforms, Cloudonix provides several levels of API keys.

The Cloudonix REST API supports authorization and authentication using on API keys that are attached to each HTTP request using the Authorization HTTP header with RFC 6750 Bearer tokens.

To make an authorized API call to The Cloudonix REST API, you need:

An API key, and record that API Key's keyId - which is the API key's "bearer token". This should be a string of 34 characters starting with the letters "XI".
Create an HTTP request to the required API.Core REST API endpoint, and set the API key's keyId in the Authorization HTTP header using the following format: Authorization: Bearer {key-token}.

API Key Authorization Levels

Cloudonix API.Core API keys grant access to different API operations according to the privileges they are granted, which we call "authorization level". A will have one of the following authorization levels:

Authorization Level	Description
`Tenant` or `Customer`	Keys with this privilege can access, create, modify and delete any resource owned by a Cloudonix customer account, at all levels - i.e. they can create domains, configure voice applications or delete subscribers.
`Domain`	Keys with this privilege can access, create, modify and delete any resource owned by a Cloudonix Domain - i.e. they cannot be used to access or change customer resources (such as users) but can access voice applications, trunks, DNIDs, subscribers, etc.
`User`	Every user that has access to the Cloudonix management cockpit is provided with a personal API key. This key abides to the users' security level - Domain or Customer.
`Voice Application`	Keys with this privilege can access, create, modify and delete any voice application level resource, which currently this is basically just the Voice Application Subscriber Data. This type of key can also be used, with less capabilities, for other operations such as executing Hosted Voice Applications and reading voice application configuration.
`Subscriber`	Keys with this privilege can perform subscriber level operations, such as connecting to subscriber services like SIP and messaging.

Additional information about API Keys data model and their scope.

API Keys REST API Endpoints

The API Keys REST API endpoints allow the provision of new API keys, lookup of API keys, and enabling or disabling of existing keys.

For ease of access, there are multiple REST API endpoints that allow the caller to access API keys in a specific context, that they have access to - for API keys for account administration vs. domain administration, you may look at the Customers API Keys Endpoint vs the Domain API Keys Endpoint.

The following REST API endpoints are available for accessing API keys according to the requested context:

/keys - Global API Keys Access Endpoint
/customers/{customer-id}/keys - Customer API Keys Endpoint
/domains/{domain}/keys - Domain API Keys Endpoint

Global API Key Access Endpoint

The global API key access is available without specific restriction to a customer account or domain and allows operations that are automatically limited to the capabilities of the API key that is used to access the API, e.g. provisioning a new key using the Global API Key Access Endpoint will create a key with identical permissions to the API key that was used to authorize the request.

The following operations are provided:

Retrieve Current API Key Details

GET /keys/self

Retrieve the API key model object for the API key that was used to authorize the call.

Request

This API call requires no additional parameters

Response

If the call is not authorized with a valid and active API key, then the server will return an HTTP 401 ("Unauthorized") error response.

Otherwise the server will return an HTTP 200 ("OK") response containing an API key model object formatted with the application/json content type.

Example

GET /keys/self
Host: api.cloudonix.io
Authorization: Bearer XI0123456789

HTTP/1.1 200 OK
Content-Type: application/json

{
  "tenant": {
    "name": "cloudonix.io"
  },
  "user": {
    "email": "odeda@cloudonix.io"
  },
  "active": true,
  "name": "odeda@cloudonix.io",
  "keyId": "XI0123456789",
  "type": "user"
}

Provision A New Customer API Key

POST /keys

Provision a customer API key with the same permissions as the current API key.

Request

This API call requires the following parameters to be provided in the body of the request as properties of an application/json encoded JSON object:

name - String: Name for the key to be provisioned.

This API call can optionally accept the following parameters if provided in the body of the request as properties of an application/json encoded JSON object:

active - Boolean: Set to true to provision the key as an active API key (the default value) or set to false for the new API key to created as inactive.

Response

If the call is not authorized with a valid and active API key, then the server will return an HTTP 401 ("Unauthorized") error response.

If the provisioning call describes a key that already exist (same permissions as the calling API key and same name as the name provided), the server will load and return the existing API key. Otherwise the server will create a new API key and return an HTTP 200 ("OK") response containing an API key model object formatted with the application/json content type.

Example

POST /keys
Host: api.cloudonix.io
Authorization: Bearer XI0123456789
Content-Type: application/json

{
  "name": "My new API key"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "tenant": {
    "name": "cloudonix.io"
  },
  "active": true,
  "name": "My new API key",
  "keyId": "XIABCDEF01234",
  "type": "customer"
}

List Existing API Keys

GET /keys

Retrieve the list of API keys that the authorizing API key has access to. The returned catalog will contain all the API keys that can be managed by the current authorization level of the authorizing API key. For example, if the authorizing key has customer account level authorization, the catalog will contain all the account administrator API keys in the customer account of the authorizing API key, all the domain administrator API keys in the customer account, all the subscriber API keys, etc.

Request

This API call requires no additional parameters.

Response

If the call is not authorized with a valid and active API key, then the server will return an HTTP 401 ("Unauthorized") error response.

Otherwise the server will return an HTTP 200 ("OK") response containing a document with the content type application/json with a JSON array containing a list of API key model objects.

Example

GET /keys
Host: api.cloudonix.io
Authorization: Bearer XI0123456789

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "tenant": {
      "name": "cloudonix.io"
    },
    "active": true,
    "name": "My new API key",
    "keyId": "XIABCDEF01234",
    "type": "customer"
  },
  {
    "tenant": {
      "name": "cloudonix.io"
    },
    "user": {
      "email": "odeda@cloudonix.io"
    },
    "active": true,
    "name": "odeda@cloudonix.io",
    "keyId": "XI0123456789",
    "type": "user"
  }
]

Update An Existing API Key

PUT /keys/{key-id}

Update an existing API key by changing the name or whether the key is active.

Request

This API call requires the following parameters in the request URL:

key-id - String: The API key's key ID (authorization token)

This API call can optionally accept the following parameters if provided in the body of the request as properties of an application/json encoded JSON object:

name - String: the new name for the API key.
active - Boolean: Set to true to enable the API key, if inactive; set to false to disable the API key, if active.

Response

If the call is not authorized with a valid and active API key, then the server will return an HTTP 401 ("Unauthorized") error response.

Otherwise the server will update the API key according to the request parameters, then return an HTTP 200 ("OK") response containing an API key model object formatted with the application/json content type.

Example

PUT /keys/XIABCDEF01234
Host: api.cloudonix.io
Authorization: Bearer XI0123456789
Content-Type: application/json

{
  "name": "New key name"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "tenant": {
    "name": "cloudonix.io"
  },
  "active": true,
  "name": "New key name",
  "keyId": "XIABCDEF01234",
  "type": "customer"
}

Delete An Existing API Key

DELETE /keys/{key-id}

Deletes an existing API key, so it is no longer available.

Request

This API call requires the following parameters in the request URL:

key-id - String: The API key's key ID (authorization token)

Response

If the call is not authorized with a valid and active API key, then the server will return an HTTP 401 ("Unauthorized") error response.

Otherwise the server will delete the specified API key, if exists, then return an HTTP 204 ("No Content") response.

Example

DELETE /keys/XIABCDEF01234
Host: api.cloudonix.io
Authorization: Bearer XI0123456789

HTTP/1.1 204 No Content

Customer API Keys Endpoint

The customer API keys endpoint restricts API key operations to a specific customer account.

The following operations are provided:

Provision A New Customer-Level API Key

POST /customers/{customer-id}/keys

Provision an API key with customer account level permissions and customer type.

Request

This API call requires the following parameters in the request URL:

customer-id - String: The UUID or name of the customer account for which an API key will be provisioned.

This API call requires the following parameters to be provided in the body of the request as properties of an application/json encoded JSON object:

name - String: Name for the key to be provisioned.

This API call can optionally accept the following parameters if provided in the body of the request as properties of an application/json encoded JSON object:

active - Boolean: Set to true to provision the key as an active API key (the default value) or set to false for the new API key to created as inactive.

Response

If the call is not authorized with a valid and active API key, that has customer account level authorization for the specified customer account, then the server will return an HTTP 401 ("Unauthorized") error response.

If the provisioning call describes a key that already exist (the same name as the name provided), the server will load and return the existing API key. Otherwise the server will create a new API key and return an HTTP 200 ("OK") response containing an API key model object formatted with the application/json content type.

Example

POST /customers/cloudonix.io/keys
Host: api.cloudonix.io
Authorization: Bearer XI0123456789
Content-Type: application/json

{
  "name": "My new API key"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "tenant": {
    "name": "cloudonix.io"
  },
  "active": true,
  "name": "My new API key",
  "keyId": "XIABCDEF01234",
  "type": "customer"
}

List Existing API Keys For Customer

GET /customers/{customer-id}/keys

Retrieve the list of API keys owned by the customer account. The returned catalog will contain all the API keys that are owned by the customer account, including all customer account level API keys, domain-level API keys, subscriber API keys, and application API keys.

Request

This API call requires the following parameters in the request URL:

customer-id - String: The UUID or name of the customer for which to list API keys.

Response

Otherwise the server will return an HTTP 200 ("OK") response containing a document with the content type application/json with a JSON array containing a list of API key model objects.

Example

GET /customers/cloudonix.io/keys
Host: api.cloudonix.io
Authorization: Bearer XI0123456789

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "tenant": {
      "name": "cloudonix.io"
    },
    "active": true,
    "name": "My new API key",
    "keyId": "XIABCDEF01234",
    "type": "customer"
  },
  {
    "tenant": {
      "name": "cloudonix.io"
    },
    "user": {
      "email": "odeda@cloudonix.io"
    },
    "active": true,
    "name": "odeda@cloudonix.io",
    "keyId": "XI0123456789",
    "type": "user"
  }
]

Update An Existing API Key For A Customer Account

PUT /customers/{customer-id}/keys/{key-id}

Update an existing API key by changing the name or whether the key is active.

Request

This API call requires the following parameters in the request URL:

cusomter-id - String: The UUID or name of the customer account to which the specified API key belongs.

key-id - String: The API key's key ID (authorization token)

This API call can optionally accept the following parameters if provided in the body of the request as properties of an application/json encoded JSON object:

name - String: the new name for the API key.
active - Boolean: Set to true to enable the API key, if inactive; set to false to disable the API key, if active.

Response

Example

PUT /customers/{customer-id}/keys/XIABCDEF01234
Host: api.cloudonix.io
Authorization: Bearer XI0123456789
Content-Type: application/json

{
  "name": "New key name"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "tenant": {
    "name": "cloudonix.io"
  },
  "active": true,
  "name": "New key name",
  "keyId": "XIABCDEF01234",
  "type": "customer"
}

Delete An Existing API Key For A Domain

DELETE /customers/{customer-id}/keys/{key-id}

Deletes an existing API key belonging to a customer account, so it is no longer available.

Request

This API call requires the following parameters in the request URL:

customer-id - String: The UUID or name of the customer account to which the specified API key belongs.
key-id - String: The API key's key ID (authorization token)

Response

Otherwise the server will delete the specified API key, if exists, then return an HTTP 204 ("No Content") response.

Example

DELETE /customers/{customer-id}/keys/XIABCDEF01234
Host: api.cloudonix.io
Authorization: Bearer XI0123456789

HTTP/1.1 204 No Content

Domain API Keys Endpoint

The domain API keys endpoint restricts access to a specific domain.

The following operations are provided:

Provision A New Domain-Level Customer API Key

POST /domains/{domain}/keys

Provision a customer API key with the same permissions as the current API key.

Request

This API call requires the following parameters in the request URL:

domain - String: The domain name of the Cloudonix domain for which an API key will be provisioned.

This API call requires the following parameters to be provided in the body of the request as properties of an application/json encoded JSON object:

name - String: Name for the key to be provisioned.

This API call can optionally accept the following parameters if provided in the body of the request as properties of an application/json encoded JSON object:

active - Boolean: Set to true to provision the key as an active API key (the default value) or set to false for the new API key to created as inactive.

Response

If the call is not authorized with a valid and active API key, that has at least a domain-level authorization for the specified customer account, then the server will return an HTTP 401 ("Unauthorized") error response.

If the provisioning call describes a key that already exist (the same name as the name provided and the same domain), the server will load and return the existing API key. Otherwise the server will create a new API key and return an HTTP 200 ("OK") response containing an API key model object formatted with the application/json content type.

Example

POST /domains/cloudonix.io/keys
Host: api.cloudonix.io
Authorization: Bearer XI0123456789
Content-Type: application/json

{
  "name": "My new API key"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "tenant": { … },
  "domain": { … },
  "active": true,
  "name": "My new API key",
  "keyId": "XIABCDEF01234",
  "type": "customer"
}

List Existing API Keys For A Domain

GET /domains/{domain}/keys

Retrieve the list of API keys owned by the domain. The returned catalog will contain all the API keys that are owned by the domain, including all domain-level API keys, subscriber API keys, and application API keys.

Request

This API call requires the following parameters in the request URL:

domain - String: The domain name of the Cloudonix domain for which to list keys.

Response

Otherwise the server will return an HTTP 200 ("OK") response containing a document with the content type application/json with a JSON array containing a list of API key model objects.

Example

GET /domains/cloudonix.io/keys
Host: api.cloudonix.io
Authorization: Bearer XI0123456789

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "tenant": { … },
    "domain": { … },
    "active": true,
    "name": "My new API key",
    "keyId": "XIABCDEF01234",
    "type": "customer"
  },
  {
    "tenant": { … },
    "domain": { … },
    "user": {
      "email": "odeda@cloudonix.io"
    },
    "active": true,
    "name": "odeda@cloudonix.io",
    "keyId": "XI0123456789",
    "type": "user"
  }
]

Update An Existing API Key For A Domain

PUT /domains/{domain}/keys/{key-id}

Update an existing API key by changing the name or whether the key is active.

Request

This API call requires the following parameters in the request URL:

domain - String: The name of the domain to which the specified API key belongs.
key-id - String: The API key's key ID (authorization token)

This API call can optionally accept the following parameters if provided in the body of the request as properties of an application/json encoded JSON object:

name - String: the new name for the API key.
active - Boolean: Set to true to enable the API key, if inactive; set to false to disable the API key, if active.

Response

Example

PUT /domains/cloudonix.io/keys/XIABCDEF01234
Host: api.cloudonix.io
Authorization: Bearer XI0123456789
Content-Type: application/json

{
  "name": "New key name"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "tenant": { … },
  "domain": { … },
  "active": true,
  "name": "New key name",
  "keyId": "XIABCDEF01234",
  "type": "customer"
}

Delete An Existing API Key For A Domain

DELETE /domains/{domain}/keys/{key-id}

Deletes an existing API key, so it is no longer available.

Request

This API call requires the following parameters in the request URL:

domain - String: The name of the domain to which the specified API key belongs.
key-id - String: The API key's key ID (authorization token)

Response

Otherwise the server will delete the specified API key, if exists, then return an HTTP 204 ("No Content") response.

Example

DELETE /domains/cloudonix.io/keys/XIABCDEF01234
Host: api.cloudonix.io
Authorization: Bearer XI0123456789

HTTP/1.1 204 No Content

Cloudonix Voice Application Access

When the Cloudonix APP.Core Voice Application Runtime executes voice applications, the voice application may need to access API.Core application-specific APIs. To authorize such access, APP.Core will automatically provision an application API key (an API key with type "application" and the customer account, domain and application set to that of the application being invoked) and provide the key ID (authorization token) in the Cloudonix CXML voice application request, using the X-CX-APIKey HTTP header. For more details, see The Voice Application Runtime Request.

API Key Authorization Levels​

API Keys REST API Endpoints​

Global API Key Access Endpoint​

Retrieve Current API Key Details​

Request​

Response​

Example​

Provision A New Customer API Key​

Request​

Response​

Example​

List Existing API Keys​

Request​

Response​

Example​

Update An Existing API Key​

Request​

Response​

Example​

Delete An Existing API Key​

Request​

Response​

Example​

Customer API Keys Endpoint​

Provision A New Customer-Level API Key​

Request​

Response​

Example​

List Existing API Keys For Customer​

Request​

Response​

Example​

Update An Existing API Key For A Customer Account​

Request​

Response​

Example​

Delete An Existing API Key For A Domain​

Request​

Response​

Example​

Domain API Keys Endpoint​

Provision A New Domain-Level Customer API Key​

Request​

Response​

Example​

List Existing API Keys For A Domain​

Request​

Response​

Example​

Update An Existing API Key For A Domain​

Request​

Response​

Example​

Delete An Existing API Key For A Domain​

Request​

Response​

Example​

Cloudonix Voice Application Access​

API Key Authorization Levels

API Keys REST API Endpoints

Global API Key Access Endpoint

Retrieve Current API Key Details

Request

Response

Example

Provision A New Customer API Key

Request

Response

Example

List Existing API Keys

Request

Response

Example

Update An Existing API Key

Request

Response

Example

Delete An Existing API Key

Request

Response

Example

Customer API Keys Endpoint

Provision A New Customer-Level API Key

Request

Response

Example

List Existing API Keys For Customer

Request

Response

Example

Update An Existing API Key For A Customer Account

Request

Response

Example

Delete An Existing API Key For A Domain

Request

Response

Example

Domain API Keys Endpoint

Provision A New Domain-Level Customer API Key

Request

Response

Example

List Existing API Keys For A Domain

Request

Response

Example

Update An Existing API Key For A Domain

Request

Response

Example

Delete An Existing API Key For A Domain

Request

Response

Example

Cloudonix Voice Application Access