Cord LogoDocs
Sign inStart now

Server Libraries

Reference /
Ask the Community

To simplify development of your Cord integration, we have server-side libraries for several languages. These make it easier to produce tokens and call our REST API

Installation #

NodeJS:
npm install @cord-sdk/server
Golang:
go get cord.com/server
Java:
implementation "com.cord:server:0.0.+"
npm install @cord-sdk/server
Copy

Generating client auth tokens #

All functions generate a JWT with HS512 and an expiration time of 1 minute.

You can get your project ID and secret from the Cord console. Store your secret securely on your servers. Don't share it with anyone, and don't include it in client code.

See our authentication guide for a description of the behavior invoked by including optional parts of the client auth token data.

NodeJS:
type PlatformUserVariables = {
    email: string;
    name?: string;
    profile_picture_url?: string;
    status?: 'active' | 'deleted';
};
type PlatformOrganizationVariables = {
    name: string;
    status?: 'active' | 'deleted';
    members?: Array<string | number>;
};
type ClientAuthTokenData = {
    app_id?: string;
    project_id?: string;
    user_id: string;
    organization_id: string;
    user_details?: PlatformUserVariables;
    organization_details?: PlatformOrganizationVariables;
};

function getClientAuthToken(project_id: string, project_secret: string, payload: Omit<ClientAuthTokenData, 'project_id' | 'app_id'>): string;
Golang:
type Status int

const (
        Unspecified Status = iota
        Active
        Deleted
)

// Any values that are left at their zero value are not sent except
// Email, which is required.
type UserDetails struct {
        Email             string
        Name              string
        ProfilePictureURL string
        Status            Status
}

// Any values that are left at their zero value are not
// sent except Name, which is required.
type OrganizationDetails struct {
        Name    string
        Status  Status
        Members []string
}

type ClientAuthTokenData struct {
        UserID              string
        OrganizationID      string
        UserDetails         *UserDetails
        OrganizationDetails *OrganizationDetails
}

func ClientAuthToken(projectID string, secret []byte, data ClientAuthTokenData) (string, error)
Java:
/* Example usage */

import com.cord.server.Cord;
import com.cord.server.ClientAuthTokenData;
import com.cord.server.PlatformUserVariables;
import com.cord.server.PlatformOrganizationVariables;

// "user" and "org" are your project's model objects
String clientToken = Cord.getClientAuthToken(
    PROJECT_ID,
    SECRET,
    new ClientAuthTokenData
          .ClientAuthTokenDataBuilder(user.getId(), org.getId())
          .organizationDetails(new PlatformOrganizationVariables
                  .PlatformOrganizationVariablesBuilder(org.getName())
                  .build())
          .userDetails(new PlatformUserVariables
                  .PlatformUserVariablesBuilder(user.getEmail())
                  .profilePictureUrl(user.getProfilePictureUrl())
                  .build())
          .build());
type PlatformUserVariables = {
    email: string;
    name?: string;
    profile_picture_url?: string;
    status?: 'active' | 'deleted';
};
type PlatformOrganizationVariables = {
    name: string;
    status?: 'active' | 'deleted';
    members?: Array<string | number>;
};
type ClientAuthTokenData = {
    app_id?: string;
    project_id?: string;
    user_id: string;
    organization_id: string;
    user_details?: PlatformUserVariables;
    organization_details?: PlatformOrganizationVariables;
};

function getClientAuthToken(project_id: string, project_secret: string, payload: Omit<ClientAuthTokenData, 'project_id' | 'app_id'>): string;
Copy

Generating server auth tokens #

All functions generate a JWT with HS512 and an expiration time of 1 minute.

You can get your project ID and secret from the Cord console. Store your secret securely on your servers. Don't share it with anyone, and don't include it in client code.

NodeJS:
function getServerAuthToken(project_id: string, project_secret: string): string;
Golang:
func ServerAuthToken(projectID string, secret []byte) (string, error)
Java:
package com.cord.server;

public class Cord {
  public static String getServerAuthToken(String projectId, String secret);
}
function getServerAuthToken(project_id: string, project_secret: string): string;
Copy

Generating Project management auth tokens #

These are customer-level server authentication tokens used to interact only with the Projects API

You can get your customer ID and secret from the Cord console. Store your secret securely on your servers. Don't share it with anyone, and don't include it in client code.

NodeJS:
function getProjectManagementAuthToken(customer_id: string, customer_secret: string): string;
Golang:
func ProjectManagementAuthToken(customer_id string, secret []byte) (string, error)
Java:
package com.cord.server;

public class Cord {
public static String getProjectManagementAuthToken(String customerId, String secret);
}
function getProjectManagementAuthToken(customer_id: string, customer_secret: string): string;
Copy

Making REST API calls #

Some of our server SDKs provide a wrapper to generate a server auth token and make a REST API call. It requires a project_id and project_secret in order to sign a token, just like the functions above. It will make a GET request by default, but can make other types of request too.

NodeJS:
type FetchOptions = {
  method?: 'GET' | 'PUT' | 'POST' | 'DELETE'; // Defaults to GET.

  project_id: string;
  project_secret: string;

  body?: string | object; // Defaults to empty body.
};

async function fetchCordRESTApi<T>(endpoint: string, opts: FetchOptions): Promise<T>;

// Some examples:

import { fetchCordRESTApi } from '@cord-sdk/server';
import type { CoreThreadData } from '@cord-sdk/types';

const allThreads = await fetchCordRESTApi<CoreThreadData[]>('v1/threads', {
  project_id: /* ... */,
  project_secret: /* ... */,
});

const { success } = await fetchCordRESTApi<{
  success: boolean;
  message: string;
}>('v1/groups/my_favorite_group/members', {
  method: 'POST',
  body: { add: usersToAdd },
  project_id: /* ... */,
  project_secret: /* ... */,
});

type FetchOptions = {
  method?: 'GET' | 'PUT' | 'POST' | 'DELETE'; // Defaults to GET.

  project_id: string;
  project_secret: string;

  body?: string | object; // Defaults to empty body.
};

async function fetchCordRESTApi<T>(endpoint: string, opts: FetchOptions): Promise<T>;

// Some examples:

import { fetchCordRESTApi } from '@cord-sdk/server';
import type { CoreThreadData } from '@cord-sdk/types';

const allThreads = await fetchCordRESTApi<CoreThreadData[]>('v1/threads', {
  project_id: /* ... */,
  project_secret: /* ... */,
});

const { success } = await fetchCordRESTApi<{
  success: boolean;
  message: string;
}>('v1/groups/my_favorite_group/members', {
  method: 'POST',
  body: { add: usersToAdd },
  project_id: /* ... */,
  project_secret: /* ... */,
});
Copy

Not finding the answer you need? Ask our Developer Community

Ask Cordy