Server-to-Server Authentication

What You Will Need

To start your integration with the Client Credentials Flow, you will need have an account with Ascenda and credentials (specifically a client_id and a client_secret) for API access.

Please reach out to your Ascenda business representative or submit a support ticket if you are new to Ascenda or our APIs. If you already have an account, you can get the client ID and client secret from the Admin Portal.

Steps (Client Credential Flow)

Step 1: Get Access Token with Client ID and Secret

Use the client ID and client secret to get an access token by using the Create Token endpoint. Assuming that authentication is successful, an access token will be returned.

Here is an example of how the payload of a response containing the access token looks:

{  
  "token_id": "1234abcd-0000-0000-0000-1234567890a",  
  "token": "ee6xxxxxxxxxxxxxxx598",  
  "access_token": "ee6xxxxxxxxxxxxxxx598",  
  "token_type": "Bearer",  
  "expires_at": 1754697600  
}

This access token will be required for authenticating subsequent API requests until it expires, is revoked, or renewed.

Step 2: Call API endpoints with Access Token

Once you have received the access token, you can perform authenticated calls to the endpoints by including the access token in the Authorization header of your API requests using the Bearer authentication scheme, which is described in detail in this document. Note that all API requests must be made over HTTPS.

Code Examples

Here are code examples in some common programming languages of an authentication call to get user details using a hypothetical token of ee6xxxxxxxxxxxxxxx598:

curl --request GET \
     --url https://api.us.ascenda.com/api/users/id \
     --header 'accept: application/json'
     --header 'Authorization: Bearer ee6xxxxxxxxxxxxxxx598'

const axios = require('axios');

axios.get('https://api.us.ascenda.com/api/users/id', {
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer ee6xxxxxxxxxxxxxxx598'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error('Error:', error);
});

import requests

url = "https://api.us.ascenda.com/api/users/id"
headers = {
    'Accept': 'application/json',
    'Authorization': 'Bearer ee6xxxxxxxxxxxxxxx598'
}

response = requests.get(url, headers=headers)
print(response.json())

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class Main {
    public static void main(String[] args) throws Exception {
        URL url = new URL("https://api.us.ascenda.com/api/users/id");
        HttpURLConnection con = (HttpURLConnection) url.openConnection();
        con.setRequestMethod("GET");
        con.setRequestProperty("Accept", "application/json");
        con.setRequestProperty("Authorization", "Bearer ee6xxxxxxxxxxxxxxx598");

        BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
        String inputLine;
        StringBuffer content = new StringBuffer();
        while ((inputLine = in.readLine()) != null) {
            content.append(inputLine);
        }
        in.close();
        con.disconnect();

        System.out.println(content.toString());
    }
}

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var client = new HttpClient();
        client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "ee6xxxxxxxxxxxxxxx598");

        var response = await client.GetAsync("https://api.us.ascenda.com/api/users/id");
        var responseString = await response.Content.ReadAsStringAsync();
        Console.WriteLine(responseString);
    }
}

<?php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "https://api.us.ascenda.com/api/users/id");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Accept: application/json",
    "Authorization: Bearer ee6xxxxxxxxxxxxxxx598"
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("https://api.us.ascenda.com/api/users/id")
request = Net::HTTP::Get.new(uri)
request["Accept"] = "application/json"
request["Authorization"] = "Bearer ee6xxxxxxxxxxxxxxx598"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end

puts response.body

package main

import (
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    client := &http.Client{}
    req, _ := http.NewRequest("GET", "https://api.us.ascenda.com/api/users/id", nil)
    req.Header.Set("Accept", "application/json")
    req.Header.Set("Authorization", "Bearer ee6xxxxxxxxxxxxxxx598")

    resp, err := client.Do(req)
    if err != nil {
        fmt.Println(err)
        return
    }
    defer resp.Body.Close()
    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}

import Foundation

let url = URL(string: "https://api.us.ascenda.com/api/users/id")!
var request = URLRequest(url: url)
request.addValue("application/json", forHTTPHeaderField: "Accept")
request.addValue("Bearer ee6xxxxxxxxxxxxxxx598", forHTTPHeaderField: "Authorization")

let task = URLSession.shared.dataTask(with: request) { data, response, error in
    if let data = data, let responseString = String(data: data, encoding: .utf8) {
        print(responseString)
    }
}

task.resume()

fetch('https://api.us.ascenda.com/api/users/id', {
  method: 'GET',
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer ee6xxxxxxxxxxxxxxx598'
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

use reqwest::header::{ACCEPT, AUTHORIZATION};
use tokio;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    let res = client
        .get("https://api.us.ascenda.com/api/users/id")
        .header(ACCEPT, "application/json")
        .header(AUTHORIZATION, "Bearer ee6xxxxxxxxxxxxxxx598")
        .send()
        .await?;

    println!("Status: {}", res.status());
    let body = res.text().await?;
    println!("Body: {}", body);

    Ok(())
}

Notes and Tips

Token Expiration

Our access tokens are returned along with a Unix timestamp format that indicates when they expire. We recommend that developers save this expiration value for their purposes to ensure they can handle token renewal appropriately and maintain uninterrupted access to the API.

Once the token expires, it can no longer be used for API calls. In such cases, you will need to request a new access token using your client ID and client secret.

Managing Client Credentials

You can view and manage your client credentials via the Admin Panel. These credentials include your client_id and client_secret, which are necessary for creating an access token.

Securing Your Credentials

Your credentials can be used to create tokens to access various endpoints in the Ascenda Platform. It is crucial to keep your credentials secure and not share them in publicly accessible areas such as GitHub or hard-code them into client-side code. We recommend you store your credentials and other sentitive information in environment variables, configuration files, or a good secret management service.