Platform API

Authentication

The Platform APIs for BlendVision One use Bearer authentication.

When crafting an API call to the Platform APIs or exploring a route within our API reference documentation, it's essential to include your API token in the header of the call. The API token is a key for integrating your application with our API. Once you obtain the token, you can include it in your API requests to authenticate and authorize your access to the API resources.

Request API token

To utilize BlendVision One, having a BlendVision One account and a valid API token is necessary. Once you have created an account, you can contact us to ask for the API token. Along with the API token, you will also receive your organization ID, which is a unique identifier for your organization within BlendVision One. This information is crucial for authenticating your API requests and ensuring proper access to the API resources.

By including the API token and organization ID in the headers of your API requests, you can securely access and interact with the BlendVision One API resources:

Authorization: Bearer <token>
x-bv-org-id: <organization-id>

Create API token

Alternatively, you can manually create the API token with specific expiry by following these steps:

  1. You should retrieve the access token after logging in with your email and password using the following API:

POST bv/account/v1/accounts/login

Here's an example of the request body:

{
  "email": "string",
  "password": "string"
}
  1. Upon successful response, you will receive an access_token that you can use for subsequent API requests. The response will contain additional information such as a refresh_token, the token's expiration duration (expires_in), and the token type (token_type).
{
  "access_token": "string",
  "refresh_token": "string",
  "expires_in": -2147483648,
  "token_type": "Bearer"
}

Remember that the access_token will eventually expire, so it's necessary to refresh it using the refresh_token provided in the response.

  1. Once you have obtained the access token, you can create the API token by the following API:

/bv/account/v1/accounts/api-token

The required parameters are:

  • name: The desired name of your new API token.
  • expired_date: The desired expiration date in ISO8601 format (e.g., "2023-12-31T23:59:59Z"). If left empty, the API token will not expire.

This will create an API token associated with your account. Importantly, you will need to possess the access token that is currently being used for authentication.

  1. After successful creation, the API will respond with the generated API token, its expiry date, and the token type. Store the token value securely as it will be used to authorize your API requests, and don't forget to replace it before its expiry date if set.
{
  "token": "my-api-token",
  "expired_date": "2024-08-24T14:15:22Z",
  "token_type": "Bearer"
}

Obtain Your Organization's ID

To get your current organization's ID, you can use the following API:
GET /bv/org/v1/organizations

Here's an example of how to do this using cURL:

curl --request GET \
  --url https://api.one.blendvision.com/bv/org/v1/organizations \
  --header 'Accept: application/json' \
  --header 'authorization: Bearer <your-api-token>'

A successful response could be:

{
  "organization": {
    "id": "string",
    "name": "string",
    "parent_id": "string",
    "type": "ORGANIZATION_TYPE_BUSINESS",
    "status": "ORGANIZATION_STATUS_ACTIVATED",
    "description": "string",
    "owner_email": "string",
    "billing_cycle": 0,
    "contract_valid_start_time": "2019-08-24T14:15:22Z",
    "contract_months": 0,
    "contract_days": 0,
    "contract_valid_end_time": "2019-08-24T14:15:22Z",
    "has_sub_orgs": true,
    "parent_name": "string",
    "license_key": "string",
    "time_zone": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z"
  }
}

The id field in the organization object is your organization's ID.

Finally, when sending subsequent API requests, including the API token and organization ID in the headers:

Authorization: Bearer <token>
x-bv-org-id: <organization-id>

Here's the sequence diagram detailing the authentication flow between the user and Platform APIs.

authentication.png

Updated