Issuing requests

The previous section contains some simple requests to the ​OpenTicket system. These requests did not require any specific headers. However, most other requests to the ​OpenTicket system require the Authorization header and have an optional Company header.

Authentication

The previous section describes how to acquire an access_token, which is used to authenticate requests. You can achieve this by adding the Authorization header to a request containing the token type ("Bearer") and the access_token separated by a single space. See the code blocks below for examples of requests containing the Authorization header.

Companies

As mentioned above, an access_token is used to authenticate requests. This access_token also authorizes requests access to one or more companies. When acquiring an access_token, you can specify zero or more companies an access_token should be able to authorize access to. These companies are listed in the token response. However, in most cases, an access_token will only authorize access to exactly one company.

The set of companies an access_token can authorize access to can be restricted to a subset using the Company header, which should contain a comma-separated list of the GUIDs of companies to which authorization should be restricted. It is also possible to add multiple Company headers containing a single GUID each.

note

The Company header is optional.

See the following code blocks for examples of requests to the ​OpenTicket system containing the Company header.

PHP

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer $accessToken",
    "Company: $GUID"
  ],
  CURLOPT_URL => "https://auth.openticket.tech/users/me"
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

GO

req, _ := http.NewRequest("PUT", "https://auth.openticket.tech/users/me", bytes.NewBuffer(body))

req.Header.Add("Authorization", "Bearer " + accessToken)
req.Header.Add("Company", "" + GUID)

resp, _ := http.DefaultClient.Do(req)

respBody, _ := io.ReadAll(resp.Body)
fmt.Println(string(respBody))

Node

const options = {
  "method": "GET",
  "headers": {
    "Authorization": `Bearer ${accessToken}`,
    "Company": `${GUID}`
  }
};

fetch("https://auth.openticket.tech/users/me", options)
  .then(response => response.json())
  .then(response => console.log(response))

Shell

curl -X GET \
  -H "Authorization: Bearer $accessToken" \
  -H "Company: $GUID" \
"https://auth.openticket.tech/users/me"

This request results in the following response

{
  "guid": "6e26d618-354b-11eb-9322-acde48001122",
  "default_company_id": "6eac75a2-354b-11eb-9322-acde48001122",
  "whitelabel_id": "6eea7dc0-354b-11eb-9322-acde48001122",
  "name": "Jane Appleseed",
  "email": "jane.appleseed@example.com",
  "phone": null,
  "created_at": "2011-12-13T11:12:13+02:00",
  "updated_at": "2020-12-13T14:15:16+01:00",
  "deleted_at": null
}

Remarks

A few remarks on the Autorization and Company headers:

• The ​OpenTicket system will respond with a 401 Unauthorized when an access_token is (no longer) valid.
• The ​OpenTicket system will respond with a 401 Unauthorized when the Company header contains the GUID of a company that the provided access_token cannot authorize access to.
• To explicitly list all companies an access_token authorizes access to in the Company header, you can use the wildcard operator *.
• A small number of endpoints must operate within the scope of a single company at a time. These also rely on the Company header. Their documentation clearly mentions the requirement to select a single company.
• Instead of adding multiple Company headers to a request, it is also possible to add a single Company header with comma-separated GUID values.
• You will only be authorized access to multiple companies if you have a valid use case, and the Company header is implemented properly.

tip

The https://auth.openticket.tech/users/me endpoint can be used to quickly check whether a token is still valid.