Getting Started

This page will help you get started with BioT API.

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

All API requests must be made over HTTPS. Calls made over plain HTTP will redirect to HTTPS. API requests without authentication may also fail.

Prerequisites

You'll need a BioT account and user credentials. If you don't have an account already, signup at biot-med.com.
Also take a minute to read this article on how to properly construct API calls.

Authorization

BioT uses API tokens to authorize access to the different APIs offered by the BioT platform.
To log in to BioT you have to make an HTTPS API call:

Request: POST
URL: https://<environment_url>/ums/v2/users/login
Body:

{
    "username": <username>,
    "password": <password>
}

If login is successful, the API call response will hold a token allowing the user to access BioT APIs

Token is: response.accessJwt.token
Save the refresh token sent to you from the login API call found at:
Refresh Token: response.refreshJwt.token

For the rest of the API calls made, you’ll have to use this token as part of the HTTPS header authorization section:

Authorization: Bearer <token>

To learn more about JWT tokens, click here.

Token Maintenance

The access token you receive from the login API call is short-lived. To maintain an active session, you need to refresh the token using the refresh token also received from the login API call.
The refresh token is a convenience token used to log in without forcing the user to retype their username and password, it has a longer expiration time than the access token.
To track the expiration time of the access token, access token expiration:
response.accessJwt.expiration
Before making an API call, check if the access token is nearing expiration (e.g., within 5 seconds). If so refresh the token before making the API call.
Refresh access token

Request: POST
URL: https://api.dev.biot-med.com/ums/v2/users/token/refresh
Body:

{
  "refreshToken": "string"
}

If the call is successful, a new access token and refresh token will be returned the same way as the regular login call

Access token is : response.accessJwt.token
Refresh Token: response.refreshJwt.token

You should also check the expiration time of the refresh token. If this token has also expired, then a new login API call with a username and password will be necessary.

📘
Note
We expect these to be sent via the authorization header.

Errors

BioT uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.). Codes in the 5xx range indicate an error with BioT servers.