Introduction

This API is used to handle circuit with Provider consuming OVHcloud API

Production link :

Prod EU : https://ovhcloudconnect.eu.ovhapis.com/1.0
Prod CA : https://ovhcloudconnect.ca.ovhapis.com/1.0
Prod US : https://ovhcloudconnect.us.ovhapis.com/1.0
Stagging : https://ovhcloudconnect.eu.build-ovhapis.com/1.0

Authentication

The authentication of the calls on the API are performed by means of a previously obtained JWT token.

The token lifespan is 2 hours, which means a new token has to be obtained regularly for your application to run smoothly.

Obtaining a JWT token

To get token, use this code:

curl -X POST "/auth/login" -d '{"email": "your_email", "password": "your_password"}'

The above command returns JSON structured like this:

{
  "expireAt": "2022-12-22T17:42:23.391450945Z",
  "token": "token_jwt_generated"
}

You can get a new JWT token by performing a POST on the /auth/login/ URL.

HTTP Request

POST /auth/login

Body Parameters

Parameter	Type	Description
email	string	User email.
password	password	User password.

Return Parameters

Parameter	Type	Description
expired_at	date-time	expiration date of the token.
token	string	JWT token generated, needed for all authenticated request.

Errors

This call uses the following error codes:

API will send errors like this for 4xx:

{
  "class": "Client::Unauthorized",
  "message": "Invalid password"
}

Error Code	Class	Messages
401	Client::Unauthorized	Invalid password
404	Client::NotFound	User not found

API will send errors like this for 5xx:

{
  "class": "Server::InternalServorError",
  "message": "personalized message"
}

Error Code	Meaning
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Using a JWT token

Example

curl -X GET "/users" -H "Authorization: Bearer your_token_generated"

Errors

When using a TOKEN in a call, you may get these errors:

API will send errors like this for 4xx:

{
  "class": "Client::BadRequest",
  "message": "Token is expired"
}

Error Code	Class	Messages
400	Client::BadRequest	Token is expired
400	Client::BadRequest	Failed to verify jwt token
401	Client::Unauthorized	Authentication token is missing
404	Client::NotFound	Token not found
404	Client::NotFound	Token no more valid

API will send errors like this for 5xx:

{
  "class": "Server::InternalServorError",
  "message": "personalized message"
}

Error Code	Meaning
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Expire the current token

To expire it :

curl -X POST "/auth/logout" -H "Authorization: Bearer your_token_generated"

You can expire JWT token by performing a POST on the /auth/logout/ URL.

HTTP Request

POST /auth/logout

Return Parameters

None

Errors

This call uses the following error codes:

API will send errors like this for 4xx:

{
  "class": "Client::Unauthorized",
  "message": "Invalid password"
}

Error Code	Class	Messages
404	Client::NotFound	Token not found

API will send errors like this for 5xx:

{
  "class": "Server::InternalServorError",
  "message": "personalized message"
}

Error Code	Meaning
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Users

The API /users allows you to manage your users defined for your provider

List the users

To get list of users:

curl -X GET "/users" -H "Authorization: Bearer your_token_generated"

The above command returns JSON structured like this:

[
  {
    "id": 1,
    "providerId": 4,
    "email": "email1@.domain.com",
    "name": "firstname1",
    "role": "admin"
  },
  {
    "id": 34,
    "providerId": 4,
    "email": "email2@domain.com",
    "name": "firstname2",
    "role": "technical"
  }
]

You can get a list of users by performing a GET on the /users/ URL.

HTTP Request

GET /users

Return Parameters

Returns a list of users:

Parameter	Type	Description
id	integer	id of the user.
providerId	integer	id of the provider.
email	string	email of the user
name	string	name of the user
role	string	role of the user

role can be:

readonly : only GET endpoints
technical : all endpoints but dont handle users
admin : all endpoints

Errors

API will send errors like this for 5xx:

{
  "class": "Server::InternalServorError",
  "message": "personalized message"
}

Error Code	Meaning
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Create an user

To create an user:

curl -X POST "/users" -H "Authorization: Bearer your_token_generated" -d '{"email": "your_email", "name": "your_name", "password": "your_password", "role": "technical"}'

The above command returns JSON structured like this:

{
  "id": 25,
  "providerId": 4,
  "email": "your_email",
  "name": "your_name",
  "role": "technical"
}

You can create an user by performing a POST on the /users/ URL.

HTTP Request

POST /users

Body Parameters

Parameter	Type	Description
email	string	user email.
password	password	user password.
name	string	name of the user
role	string	role of the user

role can be:

readonly : only GET endpoints
technical : all endpoints but dont handle users
admin : all endpoints

password must be:

8 chars min
need numericals
need upper case chars
need lower case chars
need special chars

Return Parameters

Parameter	Type	Description
id	integer	id of the user.
providerId	integer	id of the provider.
email	string	email of the user
name	string	name of the user
role	string	role of the user

Errors

This call uses the following error codes:

API will send errors like this for 4xx:

{
  "class": "Client::Unauthorized",
  "message": "only admin can create user"
}

Error Code	Class	Messages
400	Client::BadRequest	name must be defined
400	Client::BadRequest	email must be defined
400	Client::BadRequest	email is not valid
400	Client::BadRequest	role must be defined
400	Client::BadRequest	role must be readonly / technical / admin
400	Client::BadRequest	password must be defined
400	Client::BadRequest	user already exists (comparing emails)
401	Client::Unauthorized	only admin can create user

Error Code	Meaning
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Get an user

To get an user:

curl -X GET "/users/1" -H "Authorization: Bearer your_token_generated"

The above command returns JSON structured like this:

{
  "id": 1,
  "providerId": 4,
  "email": "email1@.domain.com",
  "name": "firstname1",
  "role": "admin"
}

You can get details about an user by performing a GET on the /users/<id> URL.

HTTP Request

GET /users/<id>

Path Parameters

Parameter	Type	Description
id	integer	id of the user to retrieve

Return Parameters

Returns an user:

Parameter	Type	Description
id	integer	id of the user.
providerId	integer	id of the provider.
email	string	email of the user
name	string	name of the user
role	string	role of the user

Errors

This call uses the following error codes:

API will send errors like this for 4xx:

{
  "class": "Client::NotFound",
  "message": "user not found"
}

Error Code	Class	Messages
400	Client::BadRequest	id must be defined
404	Client::NotFound	user not found

API will send errors like this for 5xx:

{
  "class": "Server::InternalServorError",
  "message": "personalized message"
}

Error Code	Meaning
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Edit an user

To edit an user:

curl -X PUT "/users/1" -H "Authorization: Bearer your_token_generated" -d '{"email": "email1@.domain.com", "name": "firstname1", "password": "your_password", "role": "admin"}'

The above command returns JSON structured like this:

{
  "id": 1,
  "providerId": 4,
  "email": "email1@.domain.com",
  "name": "firstname1",
  "role": "admin"
}

You can edit details about an user by performing a PUT on the /users/<id> URL.

HTTP Request

PUT /users/<id>

Path Parameters

Parameter	Type	Description
id	integer	id of the user to edit

Body Parameters

You can choose to edit one or more of these parameters:

Parameter	Type	Description
email	string	user email.
password	password	user password.
name	string	name of the user
role	string	role of the user

role can be:

readonly : only GET endpoints
technical : all endpoints but dont handle users
admin : all endpoints

password must be:

8 chars min
need numericals
need upper case chars
need lower case chars
need special chars

Return Parameters

Parameter	Type	Description
id	integer	id of the user.
providerId	integer	id of the provider.
email	string	email of the user
name	string	name of the user
role	string	role of the user

Errors

This call uses the following error codes:

API will send errors like this for 4xx:

{
  "class": "Client::NotFound",
  "message": "user not found"
}

Error Code	Class	Messages
400	Client::BadRequest	id must be defined
400	Client::BadRequest	email is not valid
400	Client::BadRequest	user already exists
400	Client::BadRequest	role must be readonly / technical / admin
401	Client::Unauthorized	only admin or user himself can edit user
401	Client::Unauthorized	only admin can change role
404	Client::NotFound	user not found

API will send errors like this for 5xx:

{
  "class": "Server::InternalServorError",
  "message": "personalized message"
}

Error Code	Meaning
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Delete an user

To delete an user:

curl -X DELETE "/users/1" -H "Authorization: Bearer your_token_generated"

You can delete an user by performing a DELETE on the /users/<id> URL.

HTTP Request

DELETE /users/<id>

Path Parameters

Parameter	Type	Description
id	integer	id of the user to delete

Return Parameters

None

Products

The API /products allows you to retrieve your products

List the products

To get list of products:

curl -X GET "/products" -H "Authorization: Bearer your_token_generated"

The above command returns JSON structured like this:

[
  {
    "capacity": 10000,
    "id": 70,
    "location": "par-loc",
    "providerReference": "internal-test"
  }
]

You can get a list of products by performing a GET on the /products/ URL.

HTTP Request

GET /products

Return Parameters

Returns a list of products :

Parameter	Type	Description
id	integer	id of the product
capacity	integer	product capacity in Mb
location	string	product location
providerReference	string	provider product reference

Errors

API will send errors like this for 5xx:

{
  "class": "Server::InternalServorError",
  "message": "personalized message"
}

Error Code	Meaning
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Get a product

To get a product:

curl -X GET "/products/70" -H "Authorization: Bearer your_token_generated"

The above command returns JSON structured like this:

[
  {
    "capacity": 10000,
    "id": 70,
    "location": "par-loc",
    "providerReference": "internal-test"
  }
]

You can get details about a product by performing a GET on the /products/<id> URL.

HTTP Request

GET /products/<id>

Path Parameters

Parameter	Type	Description
id	integer	id of the product to retrieve

Return Parameters

Returns a product:

Parameter	Type	Description
id	integer	id of the product
capacity	integer	product capacity in Mb
location	string	product location
providerReference	string	provider product reference

Errors

This call uses the following error codes:

API will send errors like this for 4xx:

{
  "class": "Client::NotFound",
  "message": "id not found"
}

Error Code	Class	Messages
400	Client::BadRequest	id must be defined
404	Client::NotFound	id not found

API will send errors like this for 5xx:

{
  "class": "Server::InternalServorError",
  "message": "personalized message"
}

Error Code	Meaning
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Circuits

The API /circuits allows you to manage your circuits

List the circuits

To get list of circuits:

curl -X GET "/circuits" -H "Authorization: Bearer your_token_generated"

The above command returns JSON structured like this:

[
  {
    "ovhCircuitId": 1,
    "bandwidth": 1000,
    "serviceKey": "EU.D019B999-2C0C-4083-A700-AFFE6F541997",
    "location": "par-loc",
    "providerCircuitId": "provider_circuit_1",
    "status": "active",
    "vlan": 5
  },
  {
    "ovhCircuitId": 8,
    "bandwidth": 1000,
    "serviceKey": "EU.A30DEDA2-83C5-41EE-9E48-68470BB64EE7",
    "location": "par-loc",
    "providerCircuitId": "provider_circuit_2",
    "status": "active",
    "vlan": 8
  }
]

You can get a list of circuits by performing a GET on the /circuits/ URL.

HTTP Request

GET /circuits

Return Parameters

Returns a list of circuits:

Parameter	Type	Description
ovhCircuitId	integer	OVHcloud circuit reference
bandwidth	integer	bandwidth max of the circuit
serviceKey	string	service key to create the circuit
location	string	location of the circuit
providerCircuitId	string	provider circuit reference
status	string	status of the circuit
vlan	integer	vlan on OVHcloud side of the circuit

status can be:

active : status is active (circuit has been created)
terminated : provider ask to terminate the circuit

Errors

API will send errors like this for 5xx:

{
  "class": "Server::InternalServorError",
  "message": "personalized message"
}

Error Code	Meaning
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Create a circuit

To create a circuit

curl -X POST "/circuits" -H "Authorization: Bearer your_token_generated" -d '{"providerCircuitId": "provider_circuit_3", "serviceKey": "2a5f504e-8699-11ed-a1eb-0242ac120002"}'

The above command returns JSON structured like this:

{
  "ovhCircuitId": 7983,
  "bandwidth": 1000,
  "serviceKey": "EU.2a5f504e-8699-11ed-a1eb-0242ac120002",
  "location": "par-loc",
  "providerCircuitId": "provider_circuit_3",
  "status": "active",
  "vlan": 7
}

You can create a circuit by performing a POST on the /circuits/ URL.

HTTP Request

POST /circuits

Body Parameters

Parameter	Type	Description
providerCircuitId	string	provider circuit reference
serviceKey	string	service key to create the circuit

Return Parameters

Parameter	Type	Description
ovhCircuitId	integer	OVHcloud circuit reference
bandwidth	integer	bandwidth max of the circuit
serviceKey	string	service key to create the circuit
location	string	location of the circuit
providerCircuitId	string	provider circuit reference
status	string	status of the circuit
vlan	integer	vlan on OVHcloud side of the circuit

status can be:

active : status is active (circuit has been created)
terminated : provider ask to terminate the circuit

Errors

This call uses the following error codes:

API will send errors like this for 4xx:

{
  "class": "Client::Unauthorized",
  "message": "only admin can create circuit"
}

Error Code	Class	Messages
400	Client::BadRequest	providerCircuitId must be defined
400	Client::BadRequest	serviceKey must be defined
400	Client::BadRequest	serviceKey status is not valid
401	Client::Unauthorized	only admin can create circuit
404	Client::NotFound	serviceKey not found

Error Code	Meaning
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Get a circuit

To get a circuit:

curl -X GET "/circuits/7983" -H "Authorization: Bearer your_token_generated"

The above command returns JSON structured like this:

{
  "ovhCircuitId": 7983,
  "bandwidth": 1000,
  "serviceKey": "EU.2a5f504e-8699-11ed-a1eb-0242ac120002",
  "location": "par-loc",
  "providerCircuitId": "provider_circuit_3",
  "status": "active",
  "vlan": 7
}

You can get details about a circuit by performing a GET on the /circuits/<ovhCircuitId> URL.

HTTP Request

GET /circuits/<ovhCircuitId>

Path Parameters

Parameter	Type	Description
ovhCircuitId	integer	OVHcloud circuit reference to retrieve

Return Parameters

Parameter	Type	Description
ovhCircuitId	integer	OVHcloud circuit reference
bandwidth	integer	bandwidth max of the circuit
serviceKey	string	service key to create the circuit
location	string	location of the circuit
providerCircuitId	string	provider circuit reference
status	string	status of the circuit
vlan	integer	vlan on OVHcloud side of the circuit

status can be:

active : status is active (circuit has been created)
terminated : provider ask to terminate the circuit

Errors

This call uses the following error codes:

API will send errors like this for 4xx:

{
  "class": "Client::NotFound",
  "message": "serviceKey not found"
}

Error Code	Class	Messages
400	Client::BadRequest	id must be defined
404	Client::NotFound	serviceKey not found

API will send errors like this for 5xx:

{
  "class": "Server::InternalServorError",
  "message": "personalized message"
}

Error Code	Meaning
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Edit a circuit

To edit a circuit:

curl -X PUT "/circuits/7983" -H "Authorization: Bearer your_token_generated" -d '{"status": "terminated"}'

The above command returns JSON structured like this:

{
  "ovhCircuitId": 7983,
  "bandwidth": 1000,
  "serviceKey": "EU.2a5f504e-8699-11ed-a1eb-0242ac120002",
  "location": "par-loc",
  "providerCircuitId": "provider_circuit_3",
  "status": "terminated",
  "vlan": 7
}

You can edit a circuit by performing a PUT on the /circuits/<ovhCircuitId> URL.

HTTP Request

PUT /circuits/<ovhCircuitId>

Path Parameters

Parameter	Type	Description
ovhCircuitId	integer	OVHcloud circuit reference to retrieve

Body Parameters

Parameter	Type	Description
status	string	status of the circuit

Errors

This call uses the following error codes:

API will send errors like this for 4xx:

{
  "class": "Client::NotFound",
  "message": "serviceKey not found"
}

Error Code	Class	Messages
400	Client::BadRequest	id must be defined
400	Client::BadRequest	status must be defined
400	Client::BadRequest	circuit status cannot be changed
400	Client::BadRequest	circuit status cannot be anything other than terminated
404	Client::NotFound	serviceKey not found

API will send errors like this for 5xx:

{
  "class": "Server::InternalServorError",
  "message": "personalized message"
}

Error Code	Meaning
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

ServiceKeys

The API /servicekeys allows you to retrieve your serviceKeys

List the serviceKeys

To get list of serviceKeys:

curl -X GET "/servicekeys" -H "Authorization: Bearer your_token_generated"

The above command returns JSON structured like this:

[
  {
    "bandwidth": 1000,
    "serviceKey": "EU.2a5f504e-8699-11ed-a1eb-0242ac120002",
    "location": "par-loc",
    "productId": 70,
    "vlan": 7
  }
]

You can get a list of servicekeys by performing a GET on the /servicekeys/ URL.

HTTP Request

GET /servicekeys

Return Parameters

Parameter	Type	Description
bandwidth	integer	service key bandwidth
serviceKey	string	service key reference
location	string	service key location
productId	integer	product linked reference
vlan	integer	vlan on OVHcloud side

Errors

API will send errors like this for 5xx:

{
  "class": "Server::InternalServorError",
  "message": "personalized message"
}

Error Code	Meaning
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Get a serviceKey

To get a serviceKey:

curl -X GET "/servicekeys/EU.2a5f504e-8699-11ed-a1eb-0242ac120002" -H "Authorization: Bearer your_token_generated"

The above command returns JSON structured like this:

{
  "bandwidth": 1000,
  "serviceKey": "EU.2a5f504e-8699-11ed-a1eb-0242ac120002",
  "location": "par-loc",
  "productId": 70,
  "vlan": 7
}

You can get a servicekey by performing a GET on the /servicekeys/<serviceKey> URL.

HTTP Request

GET /servicekeys/<serviceKey>

Path Parameters

Parameter	Type	Description
serviceKey	string	service key reference

Return Parameters

Parameter	Type	Description
bandwidth	integer	service key bandwidth
serviceKey	string	service key reference
location	string	service key location
productId	integer	product linked reference
vlan	integer	vlan on OVHcloud side

Errors

This call uses the following error codes:

API will send errors like this for 4xx:

{
  "class": "Client::NotFound",
  "message": "servicekey not found"
}

Error Code	Class	Messages
400	Client::BadRequest	servicekey must be defined
404	Client::NotFound	servicekey not found

API will send errors like this for 5xx:

{
  "class": "Server::InternalServorError",
  "message": "personalized message"
}

Error Code	Meaning
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Use Case

sequenceDiagram participant Provider participant Customer participant OVHcloud Note over Provider,OVHcloud: Creation Customer ->> OVHcloud : Create order request OVHcloud -->> Customer : Order Confirmed, send ServiceKey Customer ->> Provider : Create Cloud Service with the ServiceKey Provider ->> OVHcloud : Send new service request (with providerCircuitId, ServiceKey, location, bandwidth) OVHcloud -->> Provider : return provision request acknowledgement with circuit information (vlan, ovhCircuitId) Note over Provider,OVHcloud: Get status Provider ->> OVHcloud : Request for circuit provisioning status OVHcloud -->> Provider : return of successful provisioning status Note over Provider,OVHcloud: Termination Provider ->> OVHcloud : Change circuit status OVHcloud -->> Provider : return of successful provisioning status