Authentication

Voiso supports two different types of authentication keys for API requests - the contact center API key and the user API key and two different types of Bearer tokens. API keys must be added to the request path or body parameters. This article outlines the distinction between keys/tokens and guides for acquiring them for authentication.

  securitySchemes:
    contactcenterApiKey:
      description: Contact center API key provided as a query parameter.
      type: apiKey
      name: key
      in: query
    contactcenterBearerToken:
      description: Contact center API key provided as a Bearer token.
      type: http
      scheme: bearer
    userApiKey:
      description: User API key provided as a query parameter.
      type: apiKey
      name: key
      in: query
    userBearerToken:
      description: User API key provided as a Bearer token.
      type: http
      scheme: bearer

Keys

'Contact center key' and 'user key' explanation

Consider that the contact center key, also known as api_key, is used across the entire contact center and is not tied to a specific user. This enables trusted integrations, where an external system can utilize the functions of the Voiso contact center without limitations.

At the same time, the user key, also known as api_key, is an attribute of a specific user configured within the contact center. The 'user key' inherits the same permissions and restrictions set up for the user. This key allows for more flexible integrations with different access levels to contact center data and features.

In most cases, and for integration debugging purposes, Voiso recommends using the 'user key' of a user with administrator permissions.

Tip: Review the individual API overview articles and API endpoint descriptions, noting which key is needed and where it belongs in the request.

How to obtain the 'contact center key'

You can request the contact center API key api_key from a Voiso account manager.

Important: Keep your contact center API key secret. If someone obtains it, they may try to make calls on behalf of your organization's account.

How to obtain the 'user key'

Some APIs require a user key for strict authorization requirements. To access resources, the user represented by the user key must have access privileges to those resources. Refer to Security Access Groups.

A user api_key is obtained in the Voiso application.

1. Navigate to Users>Users.
2. Use Search to find the user (User name).
3. Open the Edit user view by clicking the user's name.
4. The user's API key api_key is in the API Key field. Copy this value and paste it into your API query.

Bearer tokens

Using API keys with Bearer tokens

Both contact center and user API keys can be used as Bearer tokens to authenticate requests to the Voiso API. When using this method, include the API key in the Authorization header of your request as Authorization: Bearer {api_key}. This approach provides an additional layer of security by keeping credentials out of query strings and logs. Each token type, contactcenterBearerToken and userBearerToken, corresponds directly to its respective API key. Use the contact center Bearer token for system-level integrations that require full access to contact center resources, and the user Bearer token for actions tied to a specific user’s permissions.

Here’s how you can follow your Bearer token section with clear, practical examples for both contact center and user authentication. The examples align with your existing documentation tone and formatting style:

Example requests

Contact center Bearer token

Use this format when authenticating requests that act at the contact center level, for example, listing campaigns or retrieving CDRs.

curl -X GET "https://cluster1.voiso.com/api/v2/cdr/campaigns" \
  -H "Authorization: Bearer {contact_center_api_key}" \
  -H "Content-Type: application/json"

In this example, the Authorization header includes the contact center API key as a Bearer token. The key grants system-wide access to the contact center’s API resources.

User Bearer token

Use this format when the request should reflect a specific user’s permissions, for example, sending an SMS or accessing user-specific data.

curl -X POST "https://cluster1.voiso.com/api/v1/{user_api_key}/sendsms" \
  -H "Authorization: Bearer {user_api_key}" \
  -H "Content-Type: application/json" \
  -d '{
        "agent": "2003",
        "number": "15555551234",
        "body": "This is a test message."
      }'

In this example, the Bearer token corresponds to a specific user’s API key, and the request will succeed or fail based on that user’s assigned permissions within the contact center.