# Integrate the Cloud Agent Admin API

The Sudo Platform Cloud Agent admin API is a pure GraphQL API. [Click here](/guides/decentralized-identity/cloud-agent/cloud-agent-admin-api/api-schema.md) 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.

```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.

```typescript
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}`,
  }
})
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sudoplatform.com/guides/decentralized-identity/cloud-agent/cloud-agent-admin-api/integrate-the-cloud-agent-admin-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.