Nuvias Logo
Documentation Powered by ReDoc

Hub API (1.1.0)

Download OpenAPI specification:Download

Support: support@siphonnetworks.com URL: https://support.siphonnetworks.com License: TBC Terms of Service

The Hub API is a REST API which provides access to all of Nuvias Hub functions for customers to use.

Introduction

This API provides access to all of the functions normally available in Hub.

Note : Access to Hub API requires that you have a credit account with Nuvias UC and are a reseller or service provider entitled to purchase from distribution. For more information on setting up an account, see this page.

The API has predictable resource-oriented URLs, accepts only JSON-encoded request bodies, returns JSON-encoded responses and uses standard HTTP response codes, authentication and verbs.

You can use this API, subject to the terms below, to access your data in Hub and perform the actions you normally would be able to based on your access permissions.

Versioning

We subscribe to the principles of semantic versioning. Patch and minor releases are backwardly compatible, but this does require you to be flexible in handling our API - we may add optional fields to endpoints or add additional data in a response as part of a minor release.

You can access specific versions of the API by specifying the version as part of the path.

Older versions of the API are available for at least 6 months after the release of a new version although we may extend this in some circumstances.

Multi-tier

Hub is multi-tier so you can represent your descendant organisations (e.g. customers or resellers) in Hub and allow them to perform actions. Access to data in Hub is determined by the organisation that you authenticate as

When describing multi-tier operations:

  • Parent: The direct parent of the organisation
  • Ancestor: Any parent, grand-parent or so on
  • Child: The direct child of an organisation
  • Descendant: Any child, grand-child and so on

For example: In the following organisation chain A > B > C > D > E: B is the parent of C, A and B are the ancestors of C, D is the child of C, D and E are the descendants of C.

Branding

We offer this API as a whitelabel service to our customers. If you're interested in this, get in touch with your account manager.

Getting help

The API is provided without formal support, however we have put together some resources to help.

First of all, check our Developer site where we publish the latest information and help available to developers, including the latest release notes.

You can also log in to Hub itself an review how the user interface works - the API is developed alongside the interface and so you can see how we're using the API and the data.

Authentication

The Hub API uses OAuth 2.0 as an authentication mechanism. To use the API you must first create an API client through the web interface for the user you wish to authenticate as. When this is complete, a Client ID and Client Secret will be displayed - please note the Secret is only displayed once.

Hub uses the Client Credentials Grant Type, requiring the API client to send a POST request to the token endpoint, along with the client ID and secret as described here. This endpoint then returns an access token and expiry time.

Subsequent requests to the API should then use the token in the Authorization header of the request in the format Authorization: Bearer thesecretapitoken.

OAuth2

Security Scheme Type OAuth2
clientCredentials OAuth Flow
Token URL: /api/v1/oauth/create_token
Scopes:

    OAuth

    OAuth tokens are used for authenticating a client to use the Hub API.

    Create OAuth token

    Creates OAuth token from API client credentials. This OAuth token can then be used to access the rest of the API.

    Request Body schema: application/x-www-form-urlencoded
    client_id
    required
    string

    API client ID (UUID)

    client_secret
    required
    string

    API client secret

    grant_type
    required
    string
    Value: "client_credentials"

    Grant type, currently only client credentials supported

    Responses

    200

    OK

    400

    Request body incorrect

    401

    Credentials error

    post/oauth/create_token

    Live

    https://hub.nuvias.com/api/v1/oauth/create_token

    Request samples

    Content type
    application/x-www-form-urlencoded
    Copy
    client_id=123e4567-e89b-12d3-a456-426614174000&client_secret=abcdefgh1234567&grant_type=client_credentials

    Response samples

    Content type
    application/json
    Copy
     Expand all Collapse all
    {
    • "access_token": "abc123",
    • "token_type": "Bearer",
    • "expires_in": 3600
    }

    Who am I?

    The whoami API is used to determine information about the logged in user.

    Get authenticated user

    Gets details about the currently authenticated user. If emulation is in progress, then all returned information (other than the real_id and real_name) will be about the emulated user.

    Authorizations:
    OAuth2

    Responses

    200

    Authenticated user

    403

    Permission denied

    get/whoami

    Live

    https://hub.nuvias.com/api/v1/whoami

    Response samples

    Content type
    application/json
    Copy
     Expand all Collapse all
    {
    • "id": 5,
    • "name": "Tom Jones",
    • "organisation": 5,
    • "real_id": 1,
    • "real_name": "Diana Ross",
    • "currency": "GBP",
    • "locale": "en",
    • "timezone": "Europe/London",
    • "admin": false,
    • "root": false,
    • "modules":
      [
      ],
    • "permissions":
      [
      ]
    }

    Organisations

    Organisations represent companies in a multi-tiered structure.

    Get organisations

    Gets a list of organisations

    Authorizations:
    OAuth2

    Responses

    200

    list of organisations

    403

    Permission denied

    get/organisations

    Live

    https://hub.nuvias.com/api/v1/organisations

    Response samples

    Content type
    application/json
    Copy
     Expand all Collapse all
    [
    • {
      }
    ]

    Get organisation addresses

    Get list of saved addresses for organisation

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer

    Responses

    200

    List of addresses

    403

    Permission denied

    404

    Not found

    get/organisations/{id}/addresses

    Live

    https://hub.nuvias.com/api/v1/organisations/{id}/addresses

    Response samples

    Content type
    application/json
    Copy
     Expand all Collapse all
    [
    • {
      }
    ]

    Products

    Products are the items that can be purchased through Hub.

    Get products

    Retrieve a list of products, paginated according to the per_page attribute. You can use a combination of the attributes in any way to filter the list.

    Note that the text parameter allows you to specify a string with which to search against the product name and also the product code or SKU. To retrieve the ID of a product if you know its SKU, simply use the text parameter with the SKU. Note that SKU or product code is not guaranteed to be unique across multiple vendors.

    Authorizations:
    OAuth2
    query Parameters
    page
    integer
    Default: 1
    Example: page=2

    The page of results to retrieve

    per_page
    integer
    Default: 1000
    Example: per_page=100

    The maximum number of results to return per page

    vendor
    Array of integers
    Example: vendor=5

    Filter by an array of vendor IDs. -1 can be used to filter by records with no vendor assigned

    type
    Array of integers
    Example: type=10

    Filter by an array of product type IDs. -1 can be used to filter by records with no product type

    text
    string
    Example: text=2200-123-123

    Filter by name or product code

    sort_by
    Array of strings
    Default: "-popularity"
    Items Enum: "-popularity" "-name" "+name" "-price" "+price"
    Example: sort_by=-popularity

    Order to sort results by. + indicates ascending, - indicates descending

    Responses

    200

    List of products

    403

    Permission denied

    get/products

    Live

    https://hub.nuvias.com/api/v1/products

    Response samples

    Content type
    application/json
    Copy
     Expand all Collapse all
    [
    • {
      }
    ]

    Get product by ID

    Gets a product by its ID

    Authorizations:
    OAuth2
    path Parameters
    id
    required
    integer

    ID of product

    Responses

    200

    Product information

    403

    Permission denied

    404

    Not found

    get/products/{id}

    Live

    https://hub.nuvias.com/api/v1/products/{id}

    Response samples

    Content type
    application/json
    Copy
     Expand all Collapse all
    {
    • "id": 1,
    • "name": "A New Phone",
    • "product_code": "NEW-PH0N3",
    • "description": "100 Lines, Full Colour, Makes Toast Too",
    • "detailed_description": "This phone is everything you need in a new device. It makes toast, orders lunch, and even has been known to save lives*\n*T&Cs apply",
    • "featured_description": "100 lines\nFull colour screen\nIn-built toaster",
    • "vendor": 5,
    • "type": 10,
    • "rrp": 110.12,
    • "price": 100.12,
    • "thumb_url": "string",
    • "main_image_url": "string",
    • "datasheet_url": "string",
    • "guide_url": "string",
    • "quickstart_url": "string",
    • "stock": 9001,
    • "provisioning":
      [
      ],
    • "maintenance":
      [
      ],
    • "shipping_cost": 20,
    • "subscription_type": "DROPBOX",
    • "rate_plans":
      [