# ovh

> Official Node.js wrapper for the OVH APIs

Latest version **2.0.3** (published 2019-11-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install ovh
pnpm add ovh
yarn add ovh
bun add ovh
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 2.0.3 |
| Published | 2019-11-05 |
| First published | 2012-09-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 104.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 148 |
| Author | Vincent Giersch |
| Maintainers | antleblanc, bnjjj, ovh |
| Keywords | OVH, API, REST, api.ovh.com |

## Links

- npm: https://www.npmjs.com/package/ovh
- Repository: https://github.com/ovh/node-ovh
- Homepage: http://ovh.github.io/node-ovh
- Issues: https://github.com/ovh/node-ovh/issues
- npm.io page: https://npm.io/package/ovh

## Dependencies (2)

- [async](https://npm.io/package/async.md) 0.9.x
- [bluebird](https://npm.io/package/bluebird.md) ^3.4.0

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 2.0.3 (latest) — 2019-11-05
- 2.0.2 — 2018-11-09
- 2.0.1 — 2016-08-10
- 2.0.0 — 2016-06-07
- 1.1.3 — 2015-01-19
- 1.1.2 — 2014-12-05
- 1.1.1 — 2014-10-26
- 1.1.0 — 2014-09-22
- 1.0.2 — 2014-01-17
- 1.0.1 — 2013-10-15
- 1.0.0 — 2013-09-27
- 0.3.8 — 2013-06-26
- 0.3.7 — 2013-06-14
- 0.3.6-2 — 2013-06-02
- 0.3.6-1 — 2013-05-06
- … 10 more at https://npm.io/package/ovh/versions

## README

[![Node.js Wrapper for OVH APIs](https://ovh.github.io/node-ovh/img/logo.png)](https://ovh.github.io/node-ovh)

The easiest way to use the [OVH.com](https://ovh.com) APIs in your [node.js](https://nodejs.org/) applications.

[![NPM Version](https://img.shields.io/npm/v/ovh.svg?style=flat)](https://www.npmjs.org/package/ovh)
[![Build Status](https://img.shields.io/travis/ovh/node-ovh.svg?style=flat)](https://travis-ci.org/ovh/node-ovh)
[![Coverage Status](https://img.shields.io/coveralls/ovh/node-ovh.svg?style=flat)](https://coveralls.io/r/ovh/node-ovh?branch=master)

```js
// Create your first application tokens here: https://api.ovh.com/createToken/?GET=/me
var ovh = require('ovh')({
  appKey: process.env.APP_KEY,
  appSecret: process.env.APP_SECRET,
  consumerKey: process.env.CONSUMER_KEY
});

ovh.request('GET', '/me', function (err, me) {
  console.log(err || 'Welcome ' + me.firstname);
});
```

You can also use the promised version like this:
```js
ovh.requestPromised('GET', '/me')
  .then(function (response) {
    //Do what you want
  })
  .catch(function (err) {
    //Return an error object like this {error: statusCode, message: message}
  });
```

## Installation

The easiest way to get the latest stable release is to grab it from the
[npm registry](https://npmjs.org/package/ovh).

```bash
$ npm install ovh
```

Alternatively, you may get latest development version directly from Git.

```bash
$ npm install git://github.com/ovh/node-ovh.git
```

## Example Usage

### Login as a user

#### 1. Create an application

Depending the API you plan to use, you need to create an application on the below
websites:

* [OVH Europe](https://eu.api.ovh.com/createApp/)
* [OVH US](https://api.us.ovhcloud.com/createApp/)
* [OVH North-America](https://ca.api.ovh.com/createApp/)
* [SoYouStart Europe](https://eu.api.soyoustart.com/createApp/)
* [SoYouStart North-America](https://ca.api.soyoustart.com/createApp/)
* [Kimsufi Europe](https://eu.api.kimsufi.com/createApp/)
* [Kimsufi North-America](https://ca.api.kimsufi.com/createApp/)

Once created, you will obtain an **application key (AK)** and an **application
secret (AS)**.

#### 2. Authorize your application to access to a customer account

To allow your application to access to a customer account using an OVH API,
you need a **consumer key (CK)**.

Here is a sample code you can use to allow your application to access to a
complete account.

Depending the API you want to use, you need to specify the below API endpoint:

* OVH Europe: ```ovh-eu``` (default)
* OVH US: ```ovh-us```
* OVH North-America: ```ovh-ca```
* SoYouStart Europe: ```soyoustart-eu```
* SoYouStart North-America: ```soyoustart-ca```
* Kimsufi Europe: ```kimsufi-eu```
* Kimsufi North-America: ```kimsufi-ca```

```js
var ovh = require('ovh')({
  endpoint: 'ovh-eu',
  appKey: 'YOUR_APP_KEY',
  appSecret: 'YOUR_APP_SECRET'
});

ovh.request('POST', '/auth/credential', {
  'accessRules': [
    { 'method': 'GET', 'path': '/*'},
    { 'method': 'POST', 'path': '/*'},
    { 'method': 'PUT', 'path': '/*'},
    { 'method': 'DELETE', 'path': '/*'}
  ]
}, function (error, credential) {
  console.log(error || credential);
});
```

```bash
$ node credentials.js
{ validationUrl: 'https://api.ovh.com/auth/?credentialToken=XXX',
  consumerKey: 'CK',
  state: 'pendingValidation' }
```

This consumer key can be scoped with a **specific authorization**.
For example if your application will only send SMS:

```javascript
ovh.request('POST', '/auth/credential', {
  'accessRules': [
    { 'method': 'POST', 'path': '/sms/*/jobs'},
  ]
}, function (error, credential) {
  console.log(error || credential);
});
```

Once the consumer key will be authorized on the specified URL,
you'll be able to play with the API calls allowed by this key.

#### 3. Let's play!

You are now be able to play with the API. Look at the
[examples available online](https://ovh.github.io/node-ovh#examples).

You can browse the API schemas using the web consoles of the APIs:

* [OVH Europe](https://eu.api.ovh.com/console/)
* [OVH US](https://api.us.ovhcloud.com/console/)
* [OVH North-America](https://ca.api.ovh.com/console/)
* [SoYouStart Europe](https://eu.api.soyoustart.com/console/)
* [SoYouStart North-America](https://ca.api.soyoustart.com/console/)
* [Kimsufi Europe](https://eu.api.kimsufi.com/console/)
* [Kimsufi North-America](https://ca.api.kimsufi.com/console/)

## Migration from 1.x.x to 2.x.x without Proxy support

For example if you use the OVH Europe API, you'll have to check on https://eu.api.ovh.com/console/ the endpoints available for your feature.

In order to have the informations about the bill with id "0123".
+ Before in 1.x.x with Proxy:

```javascript
ovh.me.bill["0123"].$get(function (err, billInformation) {

});
```

+ Now in 2.x.x with promise:

```javascript
ovh.requestPromised('GET', '/me/bill/0123') //This route has been found at https://eu.api.ovh.com/console/
  .then(function (billInformation) {

  })
  .catch(function (err) {

  });
```

## Full documentation and examples

The full documentation is available online: https://ovh.github.io/node-ovh.

## Hacking

### Get the sources

```bash
git clone https://github.com/ovh/node-ovh.git
cd node-ovh
```

You've developed a new cool feature? Fixed an annoying bug? We'd be happy
to hear from you!

### Run the tests

Tests are based on [mocha](https://mochajs.org/).
This package includes unit and integration tests.

```
git clone https://github.com/ovh/node-ovh.git
cd node-ovh
npm install -d
npm test
```

Integration tests use the OVH /domain/zone API, the tokens can be created
[here](https://api.ovh.com/createToken/).

```
export APP_KEY=xxxxx
export APP_SECRET=yyyyy
export CONSUMER_KEY=zzzzz
export DOMAIN_ZONE_NAME=example.com
npm run-script test-integration
```

### Documentation

The documentation is based on [Github Pages](https://pages.github.com/) and is
available in the *gh-pages* branch.


## Supported APIs

### OVH Europe

- **Documentation**: https://eu.api.ovh.com/
- **Community support**: api-subscribe@ml.ovh.net
- **Console**: https://eu.api.ovh.com/console
- **Create application credentials**: https://eu.api.ovh.com/createApp/
- **Create script credentials** (all keys at once): https://eu.api.ovh.com/createToken/

### OVH US

- **Documentation**: https://api.us.ovhcloud.com/
- **Console**: https://api.us.ovhcloud.com/console/
- **Create application credentials**: https://api.us.ovhcloud.com/createApp/
- **Create script credentials** (all keys at once): https://api.us.ovhcloud.com/createToken/

### OVH North America

- **Documentation**: https://ca.api.ovh.com/
- **Community support**: api-subscribe@ml.ovh.net
- **Console**: https://ca.api.ovh.com/console
- **Create application credentials**: https://ca.api.ovh.com/createApp/
- **Create script credentials** (all keys at once): https://ca.api.ovh.com/createToken/

### SoYouStart Europe

- **Documentation**: https://eu.api.soyoustart.com/
- **Community support**: api-subscribe@ml.ovh.net
- **Console**: https://eu.api.soyoustart.com/console/
- **Create application credentials**: https://eu.api.soyoustart.com/createApp/
- **Create script credentials** (all keys at once): https://eu.api.soyoustart.com/createToken/

### SoYouStart North America

- **Documentation**: https://ca.api.soyoustart.com/
- **Community support**: api-subscribe@ml.ovh.net
- **Console**: https://ca.api.soyoustart.com/console/
- **Create application credentials**: https://ca.api.soyoustart.com/createApp/
- **Create script credentials** (all keys at once): https://ca.api.soyoustart.com/createToken/

### Kimsufi Europe

- **Documentation**: https://eu.api.kimsufi.com/
- **Community support**: api-subscribe@ml.ovh.net
- **Console**: https://eu.api.kimsufi.com/console/
- **Create application credentials**: https://eu.api.kimsufi.com/createApp/
- **Create script credentials** (all keys at once): https://eu.api.kimsufi.com/createToken/

### Kimsufi North America

- **Documentation**: https://ca.api.kimsufi.com/
- **Community support**: api-subscribe@ml.ovh.net
- **Console**: https://ca.api.kimsufi.com/console/
- **Create application credentials**: https://ca.api.kimsufi.com/createApp/
- **Create script credentials** (all keys at once): https://ca.api.kimsufi.com/createToken/

## Related links

- **Contribute**: https://github.com/ovh/node-ovh
- **Report bugs**: https://github.com/ovh/node-ovh/issues
- **Download**: https://npmjs.org/package/ovh

---
_Source: https://npm.io/package/ovh · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._