Skip to main content

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 previously, 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.

$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;

These requests result 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.