Requesting a token

Requesting authorization

The previous section shows how to register an application as an OAuth client. This application can now request authorization from a user to access ​Eventix resources on their behalf (see remarks for more details on how the application exactly accesses these resources). This request requires the following information:

• identifier: provided after creating the OAuth Client on the dashboard.
• redirect URL: provided after creating the OAuth Client on the dashboard.
• state: a (random) identifier, which the application uses to identify the response.

Redirect a user of the application to https://auth.openticket.tech/tokens/authorize and embed this information as query parameters. See the following code blocks for examples. In these examples, some of the information mentioned above is stored in the form of environment variables.

PHP

// Laravel
Route::get("/redirect", function (Request $request) {
    $request->session()->put("state", $state = Str::random(40));

    return redirect("https://auth.openticket.tech/tokens/authorize?" . http_build_query([
        "client_id" => env("OAUTH_CLIENT_ID", ""),
        "redirect_uri" => env("OAUTH_CLIENT_REDIRECT", ""),
        "response_type" => "code",
    "state" => $state,
    ]));
});

GO

var state = "RANDOM STRING"

http.HandleFunc("/redirect", func(w http.ResponseWriter, req *http.Request) {
    uri := fmt.Sprintf("https://auth.openticket.tech/tokens/authorize?client_id=%v&redirect_url=%v&state=%v&response_type=code",
        os.Getenv("OAUTH_CLIENT_ID"),
        os.Getenv("OAUTH_CLIENT_REDIRECT"),
        state
    )

    http.Redirect(w, req, uri, http.StatusSeeOther)
})

http.ListenAndServe(":8080", nil)

Node

let state = "RANDOM STRING";

http.createServer(async function(req, res) {
    let route = url.parse(req.url).pathname;

    if (route === "/redirect") {
        let url = new URL("https://auth.openticket.tech/tokens/authorize");
        url.searchParams.append("client_id", process.env.OAUTH_CLIENT_ID);
        url.searchParams.append("redirect_uri", process.env.OAUTH_CLIENT_REDIRECT);
        url.searchParams.append("response_type", "code");
        url.searchParams.append("state", state);

        res.writeHead(302, {
            Location: url.toString()
        });

        res.end();
    }
}).listen(8080);

Shell

# Shell does not properly process the redirect.

When a user is redirected, they can either approve or decline the request of the application to access their ​Eventix resources. In either case, they will be redirected to the redirect URL. In case the user approves the request for access, the redirect URL will contain the following query parameters:

• code: the authorization code that can be used to request a token.
• state: the same value that was included with the redirect to https://auth.openticket.tech/tokens/authorize.

caution

Each code can only be used once and expires quickly. This code is not a token, and cannot be used to authenticate requests to the ​Eventix systems. It can only be used to request a token.

Requesting a token

To actually request a token, make a POST request to https://auth.openticket.tech/tokens. This request requires the following information:

• grant_type: the type of grant needed, in this case "authorization_code."
• client_id: the same identifier as used in the redirect. Provided after creating the OAuth Client on the dashboard.
• client_secret: provided after creating the OAuth Client on the dashboard.
• redirect_uri: the same redirect URL as used in the redirect. Provided after creating the OAuth Client on the dashboard.
• code: the code parameter from the authorization response.

See the following code blocks for examples. Just like before, some of the information mentioned above is stored in the form of environment variables.

PHP

// Laravel
Route::get("/callback", function (Request $request) {
    $state = $request->session()->pull("state");

    $response = (new GuzzleHttp\Client)->post("https://auth.openticket.tech/tokens", [
        "form_params" => [
            "grant_type" => "authorization_code",
            "client_id" => env("OAUTH_CLIENT_ID", ""),
            "client_secret" => env("OAUTH_CLIENT_SECRET", ""),

            "redirect_uri" => env("OAUTH_CLIENT_REDIRECT", ""),
            "code" => $request->code,
        ],
    ]);

    return json_decode((string) $response->getBody(), true);
});

GO

http.HandleFunc("/callback", func(w http.ResponseWriter, req *http.Request) {
    resp, _ := http.PostForm("https://auth.openticket.tech/tokens", url.Values{
        "grant_type":    {"authorization_code"},
        "client_id":     {os.Getenv("OAUTH_CLIENT_ID")},
        "client_secret": {os.Getenv("OAUTH_CLIENT_SECRET")},
        "redirect_url":  {os.Getenv("OAUTH_CLIENT_REDIRECT")},
        "code":          req.URL.Query()["code"],
    })

    io.Copy(w, resp.Body)
})

http.ListenAndServe(":8080", nil)

Node

http.createServer(async function(req, res) {
    let route = url.parse(req.url).pathname;

    if (route === "/callback") {
        let query = url.parse(req.url, true).query;

        const options = {
            "method": "POST",
            "headers": {
            "Content-Type": "application/json",
        },
        "body": JSON.stringify({
            grant_type: "authorization_code",
            client_id: process.env.OAUTH_CLIENT_ID,
            client_secret: process.env.OAUTH_CLIENT_SECRET,
            redirect_uri: process.env.OAUTH_CLIENT_REDIRECT,
            code: query.code,
        }),
    };

    await fetch("https://auth.openticket.tech/tokens", options)
        .then(response => response.json())
        .then(response => res.end(JSON.stringify(response)))
    }
}).listen(8080);

Shell

# Shell does not receive requests.

This requests results in the following response

{
  "token_type": "Bearer",
  "expires_in": 259200,
  "access_token": "THE_ACTUAL_TOKEN",
  "refresh_token": "REFRESH_TOKEN",
  "refresh_token_expires_in": 31535999,
  "info": {
      ...
  }
}

Token response

Besides the token, the response to the request above contains additional information:

• token_type: the type of the token issued, needed when using the access_token to authenticate requests.
• access_token: the actual access token, which can be used to authenticate requests.
• expires_in: the time-to-live (TTL) in seconds of the access_token.
• refresh_token: a token which can be used to request a new access_token.
• refresh_token_expires_in: the time-to-live (TTL) in seconds of the refresh_token.
• info:
  • user: information on the user.
  • roles: the names of the roles of the user.
  • companies: information on all the companies of the user this token grants access to.
  • whitelabel: information on the whitelabel.

Token expiration

Neither the access_token nor the refresh_token are valid indefinitely. The tokens have a Time To Live (TTL), which can be inferred from the expires_in and refresh_token_expires_in fields from the token response. In general, the following two statements about these TTLs hold:

0. refresh_token_expires_in is much greater than expires_in, to ensure access to the ​Eventix systems is maintained even when access is only incidental.
1. The TTL's are constant.

caution

These statements cannot be relied upon to hold forever. When needed, these values can be changed without any prior notice. TTLs for previously issued tokens will not be changed retroactively.