Integrate the Cloud Agent Admin API

Integrate your application with the Cloud Agent admin API

The Sudo Platform Cloud Agent admin API is a pure GraphQL API. Click here to view the full schema.

To integrate, simply make HTTP requests to the admin API of your deployed Cloud Agent instance. Server-side applications can use an API key for authentication, meanwhile client-side applications can use a user's login credentials and resultant bearer token for authentication. Keep your API key secure. Never give a client-side application access to your API key.

Integrate server-side application using API Key

If calling the admin API from a server-side application, set the x-api-key header to the admin API key for your Cloud Agent instance. GraphQL queries and mutations always use the POST HTTP method. Insert your GraphQL query or mutation as a string into the request body. Following is an example of using fetch to make HTTP requests in TypeScript.

async function callWithApiKey(gql: string) {
  const adminApiUrl: string = '' // Set the URL to your Cloud Agent instance's admin API.
  const adminApiKey: string = '' // Set your admin API key.

  const response = await fetch(adminApiUrl, {
    method: 'POST',
    body: gql,
    headers: {
      'Content-Type': 'application/json',
      Accept: 'application/json',
      'x-api-key': adminApiKey,
    }
  })

  if (response.status !== 200) {
    throw `HTTP response status ${response.status}`
  }

  const json = JSON.parse(await response.text())

  if (json.errors) {
    throw `GraphQL error when resolving ${json.errors[0].path}: ${json.errors[0].message}`
  }

  return json.data
}

// The following example GraphQL query fetches recent basic messages for a connection.
const exampleGqlQuery: string = `{
  connection(
    connectionId: "001fe530-3562-41d6-a631-3df9c7ae1f38"
  ) {
    id
    alias
    basicMessages(
      page: {}
    ) {
      items {
        id
        content
        timestamp
        direction
      }
      nextToken
    }
  }
}`
const queryResponse = await callWithApiKey(exampleGqlQuery)
const connectionAlias: string = queryResponse.connection.alias
const messages: BasicMessage[] = queryResponse.connection.basicMessages.items

// The following example GraphQL mutation sends a basic message to a connection.
const exampleGqlMutation: string = `mutation {
  sendBasicMessage(
    connectionId: "001fe530-3562-41d6-a631-3df9c7ae1f38"
    content: "Hello Bob"
  ) {
    id
    content
    timestamp
    direction
  }
}`
const mutationResponse = await callWithApiKey(exampleGqlMutation)
const sentMessageId = mutationResponse.sendBasicMessage.id

Integrate client-side application using Bearer Token

If calling the Cloud Agent admin API directly from a client-side application, the user of the client-side application would first need to be authenticated using their user login credentials, which would return a bearer token. This bearer token can then be used to authenticate HTTP requests to the admin API. The example code found above still applies - simply replace the fetch call's auth method.

const adminApiUrl: string = '' // Set the URL to your Cloud Agent instance's admin API.
const bearerToken: string = '' // Set the bearer token for the active authenticated user.

await fetch(adminApiUrl, {
  method: 'POST',
  body: gql,
  headers: {
    'Content-Type': 'application/json',
    Accept: 'application/json',
    Authorization: `Bearer ${bearerToken}`,
  }
})