v2 Access Control

Access to the Cedexis API is controlled using the OAuth 2.0 protocol.

The Cedexis API supports OAuth 2.0's Client Credentials Flow for authorization. Using the Client Credentials Flow, you'll first manually create an API client in the Cedexis Portal, then you'll use the client's id and secret to request an access token, and finally you'll pass the access token along with all of your API requests.

Note: The following examples are presented in curl. Feel free to adapt these examples to your favorite programming language.

Steps

1. Sign Up
2. Create an API Client
3. Request an Access Token
4. Access the API
5. Access Token Expiration

Sign Up

If you haven't done so already, the first step in getting API access is to sign up for a Cedexis account. You can proceed to the next step once you're able to log into the Cedexis Portal.

Create an API Client

Creating an API client allows to you access the Cedexis API. You'll create the client by logging into the Cedexis Portal and creating a client by providing a client_id. Your client will be created, along with a client_secret that only you know. You'll use those values later when requesting an access token from the API.

1. Log into the Cedexis Portal
2. Navigate to My Account -> API -> OAuth Configuration. If you do not see this option in the navigation menu, it means your portal login Id has not been assigned the proper role for API access. Contact your sales representative and request access to the portal API.
3. Add a new OAuth client by entering a short but descriptive client id in the client_id field and clicking Add New Client.
4. When your new client is created, make note of both the client_id and client_secret as these are the credentials you'll use to access the API

Note: your client_secret is essentially a password - because it is precious, keep it secret, keep it safe.

Request an Access Token

Now that you've got a client_id and client_secret, you can request an access_token. An access_token is essentially a long-lived token that will allow your client to call API methods. Access tokens issued by the API are long lived, so just request one and save it to use for future API calls. Once you get an access_token, you will include it in all future API requests.

Request an access_token

Use your client_id and client_secret:

curl https://api.cedexis.com/api/oauth/token \
   -d 'client_id=YOUR_CLIENT_ID' \
   -d 'client_secret=YOUR_CLIENT_SECRET' \
   -d 'grant_type=client_credentials'

Save the access_token

You should receive a JSON response similar to the following that conforms to the OAuth 2.0 Access Token Response format:

{
    "access_token": "6c0d7e8e-2ed8-4827-bd4f-5d5077fd8866",
    "token_type": "bearer",
    "expires_in": 0,
    "value": "6c0d7e8e-2ed8-4827-bd4f-5d5077fd8866",
    "expiration": null,
    "tokenType": "bearer",
    "refreshToken": null,
    "scope": [],
    "additionalInformation": {},
    "expired": false,
    "expiresIn": 0
}

Make special note of the access_token field. In the response above, the access_token is 6c0d7e8e-2ed8-4827-bd4f-5d5077fd8866.

You'll notice that some of the values are repeated under different key names - they can be safely ignored if they are not mentioned in the specification.

Access the API

You can use the access_token to make API requests:

curl https://api.cedexis.com/api/v2/meta/system.json/ping \
   -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

You should see a response containing the current server time:

{
  "result":"pong"
}

Here are a few other endpoints that you can quickly try out:

• https://api.cedexis.com/api/v2/reporting/applications/dns.json
• https://api.cedexis.com/api/v2/reporting/platforms.json
• https://api.cedexis.com/api/v2/reporting/subcontinents.json

Access Token Expiration

There currently isn't an explicit expiration policy for access tokens. Therefore, it's recommended that you wrap your API code in an error handling block (like a try/catch) and watch for a 401 Unauthorized HTTP status code. You can then request a new access token and resend your original API request.