Scopes

Cloudonix offers advanced security by implementing a detailed access control policy. This approach ensures that developers, voice applications, and external resources can only access the specific resources they are permitted to use, without exposing other data. Unlike other CPaaS platforms where an API key grants unrestricted access, Cloudonix provides the ability to generate API keys tailored to different data models and access permissions. This ensures a more secure and controlled environment.

Bearer Tokens

All Cloudonix API keys are implemented as Bearer Token keys, in accordance with the specifications outlined in RFC 6750, Section 2.1. This means that authentication is handled through a token that is included in the HTTP headers of requests, ensuring a secure and standardized method for accessing API resources.

Request Example:

$ curl 'https://api.cloudonix.io/customers/self' \
--header 'Authorization: Bearer XI•••••••••••••••' -s

Access Scopes

Platform Scopes

Key Type	Description	Customer	Domain	Voice Application	Subscriber
Customer	A Customer key (AKA: Tenant key) has access to all customer owned resources.
Domain	A Domain key has access to all domain owned resources, such as voice trunks, subscribers, etc.
Subscriber	A Subscriber key has access to its own resources only, eg. the subscriber profile.
Voice Application	A Voice Application key has access to its own resources only, eg. the voice application profile.

User Scope

When a user is provisioned to access the Cloudonix Cockpit, they are automatically assigned a User token. This token provides access to all resources available through the Cockpit. Users can be created with access at either the Customer scope (eg. the first administrative user) or the Domain scope (eg. a domain administrator). Once created, the User inherits the same access privileges as the scope it was created at.

User Tokens

As a developer, the User token is provided as a personal means of communicating with the Cloudonix API. Using a User token in your applications is highly discouraged, as the User token has elevated access rights and may be abused by a remote application and/or user, without proper control.

API Key Endpoints

The following are the releant API key endpoints, depending on the scope being used.

warning

When using a higher scope API key to access an resource owned data model, YOU MUST access the resource via the API key parent scope endpoint. For example, assuming the following API keys:

Customer API-Key: XI1
Domain API-Key: XI2

If using the Customer API-Key, to access domain resources, we must use the following endpoint: /customers/{customer-id/domains/{domain-name}/keys{/key-id}. If we were using the Domain API-Key, the endpoint would be as following: /domains/{domain-name}/keys{/key-id}. Each API-Key automatically defined the highest scope to be used.

Get API Keys

With Customer API Key
GET /customers/{identifier|"self"}/keys[/{key-id}]

With Domain API Key
GET /domains/{identifier}/keys[/{key-id}]

With Voice Application API Key
GET /applications/{identifier}/keys[/{key-id}]

With Subscriber API Key
GET /subscribers/{identifier}/keys[/{key-id}]

info

This request will return ALL customer API keys - may be a large JSON array of objects.

Example

[
    {
        "id": •••••••••••••••,
        "tenantId": •••••••••••••••,
        "domainId": •••••••••••••••,
        "applicationId": •••••••••••••••,
        "subscriberId": null,
        "userId": null,
        "active": true,
        "name": "API Key Description",
        "keyId": "API Key Text",
        "secret": null,
        "type": "application",
        "createdAt": "2024-08-11T11:13:35Z",
        "modifiedAt": "2024-08-19T10:11:22Z",
        "deletedAt": null,
        "activeAt": "2024-08-19T10:11:22Z",
        "tenant-id": •••••••••••••••,
        "tenant": {
            •••••••••••••••,
        },
        "domain-id": •••••••••••••••,
        "domain": {
            •••••••••••••••
        },
        "subscriber-id": •••••••••••••••,
        "subscriber": {
            •••••••••••••••
        },
        "application-id": •••••••••••••••,
        "application": {
            •••••••••••••••
        }
    }
]

Immutable Properties

Property	Type	Description
tenantId	Integer	Customer numerical ID.
domainId	Integer	Domain numerical ID, available for domain and lower scope resources only.
applicationId	Integer	Voice application numerical ID, available for voice application scope resources only.
subscriberId	Integer	Subscriber numerical ID, available for subscribers cope resources only.
name	String	API Key name.
keyId	Object	A customer settings object, describing optional customer configurations.
type	String	API Key type. See: Voice API Overview.
tenant	Object	Customer object. See: Customer Data Model
domain	Object	Domain object. See: Domain Data Model
subscriber	Object	Subscriber object. See: Subscriber Data Model
application	Object	Voice Application object. See: Voice Application Data Model
createdAt	ISO-8601 Timestamp	API Key creation timestamp, in ISO-8601 format.
modifiedAt	ISO-8601 Timestamp	API Key modification timestamp, in ISO-8601 format.
deletedAt	ISO-8601 Timestamp	API Key deletion timestamp, in ISO-8601 format.
activeAt	ISO-8601 Timestamp	API Key activation timestamp, in ISO-8601 format.

API Key Types

Key Type	Description
customer	A customer backend applicationassociatd API key, normally a remote server application backend.
user	A Cloudonix cockpit user account associatd API key.
application	A voice application associatd API key.
subscriber	A subscriber associated API key.

Create API Key

With Customer API Key
POST /customers/{identifier|"self"}/keys

With Domain API Key
POST /domains/{identifier}/keys

With Voice Application API Key
POST /applications/{identifier}/keys

With Subscriber API Key
POST /subscribers/{identifier}/keys

Create customer API Key Example

$ curl 'https://api.cloudonix.io/customers/self' \
--header 'Authorization: Bearer XI•••••••••••••••' -s
--data '{
    "name": "Customer API Key Name"
  }'

Delete API Key

With Customer API Key
DELETE /customers/{identifier|"self"}/keys/{key-id}

With Domain API Key
DELETE /domains/{identifier}/keys/{key-id}

With Voice Application API Key
DELETE /applications/{identifier}/keys/{key-id}

With Subscriber API Key
DELETE /subscribers/{identifier}/keys/{key-id}

Delete customer API Key Example

$ curl 'https://api.cloudonix.io/customers/self/XI1234567890' \
--request DELETE
--header 'Authorization: Bearer XI•••••••••••••••' -s