API Requirements

Any call for the API requires the following headers in the REQUEST header except for the get_token API call

• Content-Type - The content type of the request must be application/json
• x-api-key - The token value for a user received from the Timbr-platform (Not needed if JWT token is configured)
• x-jwt-token - The JWT access token value for a user received from the Timbr-platform (Only required if JWT token is configured)

For the get_token endpoint, the following headers are required instead of the x-api-key header

• Authorization - The authorization bearer of a base64 username/password combination encrypted with the salt as defined in the API_AUTH_SALT environment variable of the timbr-api service

---

How to get a token for a user from the Timbr platform

For the following example, we use the following assumption: The endpoint https://timbr-sample.company.com as if the Timbr-Platform is running and configured

1. Login to the timbr-platform endpoint (i.e. - https://timbr-sample.company.com)
2. Access the endpoint - https://timbr-sample.company.com/timbr/get_timbr_user_token/
3. Save the value of the token to be used as the x-api-key of the requests.

---

How to get a token from the Timbr API Service

To obtain an API token through the Timbr API Service, it is necessary to create an Authorization Bearer token. The Timbr API Service utilizes Fernet symmetric encryption, as specified in the Python cryptography library, for the generation of the Authorization Bearer Token. This Bearer Token is subsequently employed in the request for the get_token endpoint to acquire the user's Timbr API token.

Steps to get a Timbr-api token using an Authorization Bearer token:

1. Create an authorization bearer token by following and running the python script provided with the installation of the Timbr API Service
2. Post a request using the authorization bearer token with the following headers to /timbr/api/get_token

Header Key	Header Value	Sample	Description
Content-Type	application/json	Content-Type: application/json	Posts a query and returns results in JSON form
Authorization	Bearer <token>	Authorization: Bearer gAAAAA....	Used for authentication and retrieval of a timbr token to be used in following requests

Request:

curl -X 'POST' \
  'https://timbr-sample.company.com/timbr/api/get_token' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer gAAA...Gy8='

Response:

• Response code: 200
• Response body:

{
  "data": [
    "tk_ab...6af3"
  ],
  "status": "success"
}

---

Required Headers in Requests

The following headers are required in any API call request (except for the get_token request)

Header Key	Header Value	Sample	Description
Content-Type	application/json	Content-Type: application/json	Posts a query and returns results in JSON form
x-api-key	***************	x-api-key: ***************	The header value is the token value for a user from the Timbr-Platform. Not required if JWT authentication is configured in the environment.
x-jwt-token	***************	x-jwt-token: ***************	The header value is the JWT access token value used to authenticate by username or email in the Timbr-Platform. Not required for environments without JWT authentication

---

Optional Headers in Requests

The following headers are optional for API call request and control the presentation of query results

Header Key	Header Value	Default Value	Description
nested	true or false	false	When this flag is set to true and the query contains the entity_id of the concept and relationships, relationship data will be presented as a nested objects in the JSON response instead of presenting the relationships as another key-value pair in the query results
api-nested-format-properties	true or false	false	When this flag is set to true, the format of properties will be available using the formatting tags of properties in the ontology
api-nested-case-sensitivity	true or false	false	When this flag is set to true and also the nested and api-nested-format-properties flags are set to true, columns will appear as they do in the SQL query or view (they will be case sensitive) as part of the query results
api-nested-format-booleans	true or false	false	When this flag is set to true and also the nested and api-nested-format-properties flags are set to true, boolean values will be returned as a string of true or false instead of 1 or 0 as part of the query results
api-nested-ignore-entity-id	true or false	false	When this flag is set to true and also the nested and api-nested-format-properties flags are set to true, the response will not include the entity_id property as part of the query results
api-nested-minimize-relationships	true or false	false	When this flag is set to true and also the nested and api-nested-format-properties flags are set to true, only the relationship names will be presented without the target concepts as part of the query results