# Onix API - Get started

**URL:** <https://community.onix.com/t/onix-api-get-started/602>\
**Category:** Knowledge base\
**Tags:** official, onix-api\
**Created:** [February 5, 2024, 7:35am UTC](https://community.onix.com/t/onix-api-get-started/602 "2024-02-05T07:35:16Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![khoa.nguyen](https://dub1.discourse-cdn.com/flex013/user_avatar/community.onix.com/khoa.nguyen/32/1004_2.png) [@khoa.nguyen](https://community.onix.com/u/khoa.nguyen)\
**Post date:** [February 5, 2024, 7:35am UTC](https://community.onix.com/t/onix-api-get-started/602/1 "2024-02-05T07:35:16Z")

</div>

# 1. Overview

Onix API has a Swagger interface, which offers developers a quick view of all available APIs. Developers can use Swagger interface to test, and we recommend developers to test on the Sandbox environment.

Production environment:

- Onix Work URL: [https://prod.onix.com/](https://prod.onix.com/)
- Onix API URL: [https://api.onix.com/](https://api.onix.com/)
- Swagger URL: [Swagger UI](https://api.onix.com/swagger/index.html)

Sandbox environment:

- Onix Work URL: [https://sandbox.onix.com/](https://sandbox.onix.com/)
- Onix API URL: [https://api-sandbox.onix.com/](https://api-sandbox.onix.com/)
- Swagger URL: [Swagger UI](https://api-sandbox.onix.com/swagger/index.html)

Data exchange format: **JSON**.

Secured by: **Token** (see [Authentication](#authentication-3)).

# 2. API requests and responses

## Requests

Onix APIs use JSON format to communicate. All available public APIs can be found on our Swagger page.

| Action | Field value | Comment |
| --- | --- | --- |
| Create | `null` | The endpoint notes section specifies the behavior of null value for that field.   
 Otherwise, the Onix Work system will **use default value** for that field. |
| Update | `null` | The endpoint notes section specifies the behavior of null value for that field.   
Otherwise, the Onix Work system will **ignore** that field, so the underlying data remains unchanged. |
| Update | `""`   
 (empty string) | Use to clear string-field data if the minimum length constraint can be equal to 0. |

## Success responses

Always have HTTP status of `200 OK`, and the body contains JSON-formatted data. Some common response types in JSON format:

- An integer.
- A boolean.
- A single string.
- Key-value pair list – key and value types are both string type.

**Note** : Parsing may be needed when using them in different types for specific endpoints.

## Error responses

| Status code | Description |
| --- | --- |
| `400` | Bad request.   
Please check your request’s parameters and body. See examples of bad request’s response below this table. |
| `401` | Unauthorized request.   
Please check if you are:  
• Missing a token.  
• Missing or using incorrect scheme: **Bearer** for short-lived token, **Key** for long-lived token. |
| `500` | System errors.  
If you encounter any issues or have questions, [contact Onix Support](https://community.onix.com/pub/contact-support) for assistance. |

**An example of standard bad requests response:**

- Validation error response: Request field contains incorrect format or invalid values.

```js
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-301ec3c5a9ce095960f403c21865b69d-7a1a2d1c823e7f70-00",
  "errors": {
    "source": [
      "Source is invalid"
    ],
    "erpOrderDate": [
      "ErpOrderDate wrong format"
    ]
  }
}

```

- Logic/state error response:

```js
[
  {
    "memberNames": [
      "workflowStatusId"
    ],
    "errorMessage": "Invalid Workflow Status Id"
  }
]

```

# 3. Authentication

Onix API uses token-based authentication. There are two types: short-lived tokens and long-lived tokens.

- Short-lived tokens use **`Bearer`** scheme. Their expiration time is set to **60 minutes**.
- Long-lived tokens use **`Key`** scheme. They don’t have an expiration time and won’t change overtime.

To use the token in Swagger:

- Click **Authorize** button to open the dialog.
- Input your token including the authorization scheme.
- Click **Authorize** again to finish. You are now ready to use Onix Work APIs.

## Acquire and use short-lived tokens

**To acquire a short-lived token,** make a POST request to the following endpoint:

```plaintext
POST /v1/Account/token

```

with the following request body:

```js
{
  "username": "your_email",
  "password": "your_password"
}

```

Where:

- `username`: your Onix Work’s account email address.
- `password`: your Onix Work’s account password.

Response:

| Status code | Response body | Comment |
| --- | --- | --- |
| `200` | A single JSON string. | A token in JSON string format, and it will expire **in 60 minutes**. |
| `400` | Error response object with title “Bad request” and status 400. | Incorrect user credentials or incorrect request body object. |

**To use short-lived token,** add the HTTP Authorization header with **`Bearer`** scheme:

```plaintext
Authorization: Bearer <token>

```

Example: Make request to `POST /v1/Account/token` with body:

```js
{
  "username": "your_email",
  "password": "your_password"
}

```

- If the account exists, the response status will be `200`, and the response body should look like this:

```auto
"eyJhbGciOiJSUzI1NiIsImtpZCI6Ijg5QzVCMDYwM0U0MjkxRDhEQkFDOUFGNUI3MzFGNDVBIiwidHlwIjoiYXQrand0In0.eyJuYmYiO*(...snipped)*"

```

- If the credentials are incorrect, the response status will be `400`, and the response body will look like:

```js
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "traceId": "00-44498d7f86769d75ed0ae336b6424d14-107b755ce0b78d35-00"
}

```

Otherwise, contact your organization administrator or [contact Support](https://community.onix.com/pub/contact-support) for further assistance.

After acquiring the security token successfully, attach the token in the authorization header for every request, using **Bearer** scheme. Replace `<your_token_here>` with your acquired token:

```plaintext
Authorization: Bearer <your_token_here>

```

## Acquire and use the long-lived token

To create and acquire the long-lived token, first, open [the Onix Work URL](https://prod.onix.com/) on the browser and sign in. Then:

1. Go to **Settings \> External data-sources \> API configuration**.
2. Select **New** \> Enter the expiry date of this token \> Save.

The token is shown only once, immediately after creation. Store it securely; later you can only copy but not view it completely again.

 ![](https://europe1.discourse-cdn.com/flex013/uploads/onix/original/2X/0/05f71b611cb229b94a5b5890766c6b704d2ea7f2.jpeg)

After you acquire the token, include it in the authorization header for every request using **Key** scheme. Replace `<your_token_here>` with your acquired token:

```plaintext
Authorization: Key <your_token_here>

```

The **Key** scheme can be omitted.

# 4. API best practices

We recommend these practices:

- **Refresh short-lived tokens:** Periodically refresh short-lived tokens to ensure continuous access.
- **Safeguard your tokens:** Treat tokens as sensitive information and store them securely.

> **Important** : The long-lived token is **specific to your company** and **stays the same** , ensuring ongoing stability. Please prioritize the security of this special token.

# 5. Terminology

- _Onix API_ — the modern version of the API designed for interacting with Onix Work efficiently.

- _The Onix Work Web API_ or _Web API_ — the earlier version of the API for interacting with Onix Work. **Deprecated**.

- _Production environment —_ the main environment, and it contains your company’s data. Data here is stored permanently.

- _Sandbox environment_ _—_ the playground environment, we recommend developers to test on this environment. Please be advised that the data within the sandbox environment is temporary and undergoes periodic restoration from the production environment in accordance with Onix Work’s scheduled processes.

- _The Onix Work system_ or _the system_ — represents the Onix API or Onix Work in general.

- _Your system_ _—_ represents you or your software using Onix API.

- _Onix Work_ — represent the Onix Work platform, typically Onix Work website via Onix Work URL (see [Overview](#overview-1)).

- _Order_ — a container that holds multiple order lines. The objective is to create multiple equipment units once the order is delivered (processed).

- _Order line_ — contains information to create equipment which has the same product type, properties, …

- _Language codes_ — integer numbers represent languages used in Onix Work system. This is useful if you are developing multilingual software. When an endpoint has `languageCode` as an optional query parameter/field, the Onix Work system will use **English** as the default language. Supported languages with language codes:
  - Norwegian – 0.
  - English – 1.
  - Swedish – 3.
  - Danish – 4.
  - Spanish – 7.

- _Company links_ — your company’s custom definition list to map between your system’s internal IDs (external IDs in Onix Work) for your customer companies and the Onix Work company IDs. There are two types of links: _supplier_ and _customer_. When specifying IDs in the request body, make sure that the provided external ID exists in the company links with the correct link type.  
To manage company links, open Onix Work on a browser, then navigate to: **Settings** module \> **External linking** \> **Company links** tab.

- _Contact links_ — same as company links, but for contacts.  
To manage contact links, open Onix Work on a browser, then navigate to:  
**Settings** module\> **External linking** \> **Contact links** tab.

- _External ID_ — a term used by Onix Work typically referring to your system’s internal ID.

- _Workflow_ — a workflow is a customized set of steps defined by your company to track specific progress. Currently, there are two types of workflows: order and order line. You can manage the workflows of your company by navigating to the Onix Work using the Onix Work URL (see section 1. Overview), then: **Settings** module\> **Workflow** \> **Order** / **Order line** tab.

- _Orders module_ — one of the main modules in Onix Work, the main purpose is to create and manage orders and order lines.

- _Settings module_ — one of the main modules in Onix Work, it helps users control different types of preferences for their company.

- _Your company­_ — current user logged in the company via tokens.

- _Customer company_ (in order endpoints) — refer to your system’s customer company.

- _Unique equipment_ — a class of equipment that is not non-unique (see below), countable, distinctive, and reusable. Borrowed equipment must be returned to the warehouse.

- _Non-unique equipment_ — a class of equipment that is either consumable goods, stock goods or part.

- _Consumable goods_ — uncountable items, such as liquids or gases, that cannot be returned to the warehouse. Consumable goods doesn’t have a serial number or a batch number.

- _Stock goods_ — countable items, often small and trivial, such as nails and screws, and are usually not intended to return to the warehouse. Stock goods doesn’t have a serial number or a batch number.

- _Part_ — countable items, often components that can combine with other parts to create a complete product.

- _Main equipment_ — it is formed by combining multiple sub equipment.

- _Sub equipment_ — component equipment, that can combine with other sub equipment (in main equipment) to create complete equipment (main equipment).

- _Process_ (an order line property) — corresponds to the `Process` field on an order line on Onix Work. It defines the action when processing the order or the order line on Onix Work. Supported values are:

# 6. Linked articles

## The order APIs

- [Part 1](https://community.onix.com/t/onix-api-transfer-orders-part-1-4-create-an-order-or-order-line/624): create and update an order, an order line and numbering an order line.
- [Part 2](https://community.onix.com/t/onix-api-transfer-orders-part-2-4-update-order-lines-properties-and-form-properties/627): update an order line’s properties and form properties.
- [Part 3](https://community.onix.com/t/onix-api-transfer-orders-part-3-4-migrate-from-web-api-to-onix-api/626): how to migrate from Web API to Onix API.
- [Part 4](https://community.onix.com/t/onix-api-transfer-orders-part-4-4-create-and-update-a-grouped-order-line/1213): create and update grouped order lines.

## Other APIs

- [Onix API – Transfer products](https://community.onix.com/t/1214)
- [Onix API - Transfer documents](https://community.onix.com/t/353)

> If you encounter any issues or have questions, kindly describe your concern and:
> 
> - Send an email to [support@onix.com](mailto:support@onix.com); OR
> - Create a topic in #Q&A to receive assistance from all Community members.