Class Client

constructor

• new Client(auth: IAuthentication, baseUrl?: string): Client

  Initializes a new Client, which allows to request data from the API. Differently to Client.authenticate([...]) it needs a tenant given and does not verify if the login is correct.

  Example

  
  const auth = new BasicAuth({
    user: 'youruser',
    password: 'yourpassword',
    tenant: 'acme'
  }); // use CookieAuth() if your platform uses oauth (only in browser!)
  
  const baseUrl = 'https://acme.cumulocity.com';
  const client = new Client(auth, baseUrl);
  (async () => {
    const { data, paging, res }); =  await client.inventory.list({ pageSize: 100 });
  })();
  Copy

  Parameters

  • auth: IAuthentication

    The Authentication strategy to use (e.g. new BasicAuth())

  • OptionalbaseUrl: string

    The URL to request (optional in browser, mandatory in node)

  Returns Client

alarm

application

audit

core

deviceRegistration

deviceRegistrationBulk

event

identity

inventory

inventoryBinary

inventoryRole

measurement

operation

operationBulk

options

realtime

role

smartGroups

smartRules

tenant

user

userGroup

userRole

setAuth

• setAuth(auth: IAuthentication): void

  Allows to change the current Authentication

  Parameters

  • auth: IAuthentication

    The new Authentication information.

  Returns void

Staticauthenticate

• authenticate(credentials: ICredentials, baseUrl?: string): Promise<Client>

  Authenticates the given user. Determines the tenant by itself via a call to tenant/currentTenant.

  Example

  
  let client: Client;
  (async () => {
   client = await Client.authenticate({
     user: 'testuser',
     password: 'password1337!'
   }, 'https://acme.cumulocity.com');
  
   //you have access to the client api now
   const { data, paging, res }); =  await client.inventory.list({ pageSize: 100 });
  })();
  Copy

  Parameters

  • credentials: ICredentials
  • OptionalbaseUrl: string

  Returns Promise<Client>

StaticauthenticateViaOAuthInternal

• authenticateViaOAuthInternal(
      credentials: ICredentials,
      baseUrl?: string,
  ): Promise<Client>

  Authenticates the given user via OAuth Internal. Determines the tenant by itself via a call to tenant/currentTenant. Login call goes to /tenant/oauth/token and the retrieved token will be added in the Authorization header to subsequent requests.

  Example

  
  let client: Client;
  (async () => {
   client = await Client.authenticateViaOAuthInternal({
     user: 'testuser',
     password: 'password1337!'
   }, 'https://acme.cumulocity.com');
  
   //you have access to the client api now
   const { data, paging, res }); =  await client.inventory.list({ pageSize: 100 });
  })();
  Copy

  Parameters

  • credentials: ICredentials
  • OptionalbaseUrl: string

  Returns Promise<Client>

StaticauthenticateViaOAuthInternalCookie

• authenticateViaOAuthInternalCookie(
      credentials: ICredentials,
      baseUrl?: string,
  ): Promise<Client>

  Authenticates the given user via OAuth Internal. Determines the tenant by itself via a call to tenant/currentTenant. Login call goes to /tenant/oauth and the retrieved token will be attached as a Cookie in browser environments to subsequent requests (using 'CookieAuth'). In none browser environments (e.g. nodejs) the retrieved token will be added in the Authorization header to subsequent requests (using 'NodeJSCookieAuth').

  Example

  
  let client: Client;
  (async () => {
   client = await Client.authenticateViaOAuthInternalCookie({
     user: 'testuser',
     password: 'password1337!'
   }, 'https://acme.cumulocity.com');
  
   //you have access to the client api now
   const { data, paging, res }); =  await client.inventory.list({ pageSize: 100 });
  })();
  Copy

  Parameters

  • credentials: ICredentials
  • OptionalbaseUrl: string

  Returns Promise<Client>

StaticdeviceBootstrap

• deviceBootstrap(options: IBootstrapOptions): Promise<Client>

  Allows to use http to register a device on the platform.

  Deprecated Please use MQTT to bootstrap a device.

  Parameters

  • options: IBootstrapOptions

  Returns Promise<Client>

StaticgetMicroserviceSubscriptions

• getMicroserviceSubscriptions(
      bootstrapCredentials: ICredentials,
      baseUrl: string,
  ): Promise<ICredentials[]>

  Retrieves microservice credentials for the subscribed tenants using provided bootstrap credentials

  Example

  
  (async () => {
   const subscriptions = await Client.getMicroserviceSubscriptions({
     tenant: process.env.C8Y_BOOTSTRAP_TENANT,
     user: process.env.C8Y_BOOTSTRAP_USER,
     password: process.env.C8Y_BOOTSTRAP_PASSWORD
   }, process.env.C8Y_BASEURL);
  
   const clients = subscriptions.map(subscription => new Client(new BasicAuth(subscription), process.env.C8Y_BASEURL));
   // you have access to the client api now
   const promiseArray = clients.map(client => client.options.tenant.detail({
     category: process.env.APPLICATION_KEY,
     key: 'someSetting'
   }));
  })();
  Copy

  Parameters

  • bootstrapCredentials: ICredentials
  • baseUrl: string

  Returns Promise<ICredentials[]>

StaticloginViaOAuthInternal

• loginViaOAuthInternal(
      credentials: ICredentials,
      bearerAuth?: true,
      baseUrl?: string,
  ): Promise<string>

  Performs the OAuth Internal login.

  If the parameter bearerAuth is set to true (default), the /tenant/oauth/token endpoint is called and a string containing the token returned.

  If the parameter bearerAuth is set to false, the /tenant/oauth endpoint is called and a Cookie should be set and the response returned. The response can be used in none browser environments to extract the set-cookie header from it.

  Example

  
  (async () => {
   const client = await Client.loginViaOAuthInternal({
     tenant: process.env.C8Y_BOOTSTRAP_TENANT,
     user: process.env.C8Y_BOOTSTRAP_USER,
     password: process.env.C8Y_BOOTSTRAP_PASSWORD
   }, true, process.env.C8Y_BASEURL);
  
   // you have access to the client api now
   const option = client.options.tenant.detail({
     category: process.env.APPLICATION_KEY,
     key: 'someSetting'
   });
  })();
  Copy

  Parameters

  • credentials: ICredentials
  • OptionalbearerAuth: true
  • OptionalbaseUrl: string

  Returns Promise<string>

• loginViaOAuthInternal(
      credentials: ICredentials,
      bearerAuth: false,
      baseUrl?: string,
  ): Promise<IFetchResponse>

  Performs the OAuth Internal login.

  If the parameter bearerAuth is set to true (default), the /tenant/oauth/token endpoint is called and a string containing the token returned.

  If the parameter bearerAuth is set to false, the /tenant/oauth endpoint is called and a Cookie should be set and the response returned. The response can be used in none browser environments to extract the set-cookie header from it.

  Example

  
  (async () => {
   const client = await Client.loginViaOAuthInternal({
     tenant: process.env.C8Y_BOOTSTRAP_TENANT,
     user: process.env.C8Y_BOOTSTRAP_USER,
     password: process.env.C8Y_BOOTSTRAP_PASSWORD
   }, true, process.env.C8Y_BASEURL);
  
   // you have access to the client api now
   const option = client.options.tenant.detail({
     category: process.env.APPLICATION_KEY,
     key: 'someSetting'
   });
  })();
  Copy

  Parameters

  • credentials: ICredentials
  • bearerAuth: false
  • OptionalbaseUrl: string

  Returns Promise<IFetchResponse>