How It Works

Using OAuth Tokens

CarrierX API requires authentication. This means that to access CarrierX portal and API, users must be registered in the system and have a valid user name and password.

For the third-party applications, the authentication is also required. Using login and password for their access is not secure. If somebody reverse-engineers your application, your credentials will get compromised. In this case, especially if you have many applications, you will have to change your credentials for all of them.

To avoid this we recommend using authorization tokens when accessing CarrierX Core API and sending requests to it.

What are OAuth Tokens?

The login credentials are too sensitive information to share them with the third-party applications. That is why CarrierX introduced authorization tokens.

The tokens allow keeping the user login and password information private and, at the same time, give access to the API to any created applications. This is considered the correct and safe way for the third-party applications to make API requests. You can easily and quickly revoke a token issued for a certain application, leaving the access for the rest of applications. Your login and password will also remain safe and you will not need to change them.

Moreover, tokens allow the partners to restrict the scopes that the application possesses and this way limit the application access to CarrierX API leaving only the scopes that the application really needs.

OAuth Flow

In the general case, before a client can access a protected resource, it must first obtain an authorization grant from the resource owner and then exchange the authorization grant for an access token.

The access token represents the grant scope, duration, and other attributes granted by the authorization grant. The client accesses the protected resource by presenting the access token to the resource server.

Open Authorization, or OAuth, is an open standard, commonly used as a way for the internet users to grant websites or applications access to their information on other websites without disclosing their passwords.

The common OAuth flow looks like the following:

OAuth Flow

  1. The client (normally, an application) requests authorization from the resource owner. The client can make this request either directly to the resource owner or via the authorization server as an intermediary.

  2. The client receives the authorization grant from the resource owner. These are the credentials representing the authorization of the resource owner. The authorization grant type depends on the method used by the client and by the support of the authorization server.

  3. The client requests an access token by authenticating with the authorization server and presenting the authorization grant.

  4. The authorization server authenticates the client and validates the authorization grant, and if valid, issues an access token.

  5. The client requests the protected resource from the resource server and authenticates by presenting the access token.

  6. The resource server validates the access token, and if valid, serves the request.

The predominant type of the access token used with OAuth is bearer tokens. Usually, a bearer token is a string of hexadecimal characters not intended to have any meaning to clients using it. It may be either short or have some internal structure when deciphered, like in JSON Web Tokens (JWT).

CarrierX also uses bearer tokens for the API access. They are normally sent in the request Authorization header:

-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

CarrierX OAuth Flow

CarrierX OAuth token API complies with the OAuth specifications, though the OAuth flow is a little bit different. This is due to the fact that CarrierX mostly uses application-to-application flow without any user participation. Thus, the system authorizes the application rather than a user, so any interactions with the users are avoided.

CarrierX OAuth flow looks like the following:

CarrierX OAuth Flow

Here, the first two steps from the common OAuth flow are replaced by CarrierX specific ones:

  1. The partner contacts CarrierX support with the registration request.

  2. In response to the request, CarrierX sends the partner an email message with the credentials to access CarrierX portal and API.

The rest of the steps coincide with those of the common OAuth flow.

After you receive the email message with the credentials, you can access the portal and go to the Account - Security Tokens portal section to see the list of the OAuth tokens available for your account by default.

Getting Access Credentials

You can generate access tokens not only using the portal but also with the API. For this, you will need the following information:

Upon request from CarrierX support, CarrierX partners receive the data and can now go on with the OAuth token generation.

Generating Tokens

After you obtain the necessary information (login, password, client ID, and client secret), you can generate a token.

First, you need to decide what grant type you will use for your new token.

CarrierX API uses two main grant types based on their functions for the tokens:

Let’s take a closer look at generating tokens using both grant types.

Using Password Grant Type

When you generate an access token for the first time, you need to use the password grant type. You send the request containing the password grant to the authorization server and it returns the created access token.

Access Token

Create an access token using the following POST request:

curl -X POST \
'https://api.carrierx.com/core/v2/oauth/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-binary 'grant_type=password&client_id=5c7965f285344165b003ce1a3202e589&client_secret=5033909114fe442cbbcb83b674dbf90c&username=carrierx_partner&password=qwerty123' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

The successful request will return a 200 response with a serialized copy of the updated OAuth Token object:

{
    "access_token": "8bfd6c6d-6291-488a-bed1-8784c195ce87",
    "client_id": "5c7965f285344165b003ce1a3202e589",
    "date_created": "2020-09-11T13:46:42.211Z",
    "date_expiration_access_token": "2120-08-18T13:46:42.169Z",
    "date_expiration_refresh_token": "2120-08-18T13:46:42.169Z",
    "date_last_accessed": null,
    "ip_last_accessed": null,
    "name": "test_token",
    "partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
    "refresh_token": "ed07dcd6-dfc5-4d7b-b7b4-891441371b3e",
    "scopes": [
        "accesscontrol.manage",
        "endpoints.manage",
        "oauth.manage",
        "partners.manage",
        "phonenumber.manage",
        "push.manage",
        "shortener.manage",
        "sms.manage",
        "storage.manage",
        "trunk_groups.manage",
        "trunk_groups.trunks.manage"
    ],
    "token_sid": "b3f45e4d-7d46-467b-9724-272f57ac420e",
    "token_type": "bearer"
}

The main attributes of the returned OAuth Token object, as defined by the OAuth specifications, are the following:

Using Refresh Grant Type

By default, access tokens expire in 30 minutes and refresh tokens expire in 60 minutes. To refresh the time during which the token remains valid, the refresh grant type can be used.

To post the request, you need to set the grant_type parameter to refresh_token, enter the client ID, client secret, and the refresh token values, and set the refresh_token_type depending on which token you want to refresh, either to refresh_token or to access_token:

curl -X POST \
'https://api.carrierx.com/core/v2/oauth/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-binary 'grant_type=refresh_token&client_id=5c7965f285344165b003ce1a3202e589&client_secret=5033909114fe442cbbcb83b674dbf90c&refresh_token=ed07dcd6-dfc5-4d7b-b7b4-891441371b3e&refresh_token_type=refresh_token' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

The successful request will return the updated OAuth Token object with the modified date_expiration_refresh_token or date_expiration_access_token value.

If you want to create a new access token but do not want to submit your credentials (login and password), use new_token as the refresh_token_type value:

curl -X POST \
'https://api.carrierx.com/core/v2/oauth/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-binary 'grant_type=refresh_token&client_id=5c7965f285344165b003ce1a3202e589&client_secret=5033909114fe442cbbcb83b674dbf90c&refresh_token=ed07dcd6-dfc5-4d7b-b7b4-891441371b3e&refresh_token_type=new_token' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

The successful request will return a newly created OAuth Token object:

{
    "access_token": "6572e254-5842-4896-8aba-d66efc26cd22",
    "client_id": "5c7965f285344165b003ce1a3202e589",
    "date_created": "2020-09-11T13:46:42.211Z",
    "date_expiration_access_token": "2120-08-18T13:46:42.169Z",
    "date_expiration_refresh_token": "2120-08-18T13:46:42.169Z",
    "date_last_accessed": null,
    "ip_last_accessed": null,
    "name": "test_token",
    "partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
    "refresh_token": "6ccc80b2-a274-4484-8a8a-11e0d2652f2b",
    "scopes": [
        "accesscontrol.manage",
        "endpoints.manage",
        "oauth.manage",
        "partners.manage",
        "phonenumber.manage",
        "push.manage",
        "shortener.manage",
        "sms.manage",
        "storage.manage",
        "trunk_groups.manage",
        "trunk_groups.trunks.manage"
    ],
    "token_sid": "83ad4985-050b-48f8-b6e9-444d2b8f5bcb",
    "token_type": "bearer"
}

The default value for the refresh_token_type parameter is access_token. This means that if you do not specify the refresh_token_type parameter in the request, the access token will be refreshed by default.

Accessing API with Token

After you receive the OAuth token, you can use it to access API.

Access API

Use the access_token attribute from the returned OAuth Token object to form the request header:

curl -X GET \
'https://api.carrierx.com/core/v2/oauth/whoami' \
-H 'Authorization: Bearer 8bfd6c6d-6291-488a-bed1-8784c195ce87'

A successful request will return the Partner object accessible with the access token.

Other Actions with OAuth Tokens

Revoking Token

If the access token is compromised or you simply want to take it out of use, you can use the following POST request to revoke the token:

curl -X POST \
'https://api.carrierx.com/core/v2/oauth/revoke' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-binary 'client_id=5c7965f285344165b003ce1a3202e589&client_secret=5033909114fe442cbbcb83b674dbf90c&token=2389a06c-4bdb-455a-aed7-e3647239b774' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

The successful request will return a 204 status code with an empty body.

Updating Token

Additionally, you can update the access token using either PATCH or PUT API methods.

The fields that you can modify include:

The request to modify the OAuth Token object will look like the following:

curl -X PATCH \
'https://api.carrierx.com/core/v2/oauth/tokens/b3f45e4d-7d46-467b-9724-272f57ac420e' \
-H 'Content-Type: application/json' \
--data-binary '{"scopes":["oauth.manage","partners.read","partners.update","push.manage"]}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

If executed successfully, it will return the updated OAuth Token object containing the modified attributes.

Further Reading

OAuth Token Object API Reference

Refer to the OAuth Token object API reference to get the complete list of its attributes and methods used with it:

OAuth Token Object

How It Works

Read the following articles to get a better understanding of how things work in CarrierX: