Skip to main content

TitanHQ Product Docs

WebTitan API Authentication

WebTitan API uses OAuth 2 with Proof Key for Code Exchange (PKCE) for authentication. PKCE is an additional layer in the OAuth 2.0 Authorization Code Flow and provides better security for use in applications that can not store a client secret, such as single-page applications.

Full WebTitan API documentation is available at https://support.titanhq.com/webtitan-api/.

With PKCE, a code verifier and a code challenge are used when exchanging the authorization code for an access token, replacing the client secret used in OAuth1. See https://www.rfc-editor.org/rfc/rfc7636 small_external_link.png for more information on PKCE.

The following are the authentication steps to get an access token which can then be used to call WebTitan API endpoints. Examples shown use the Postman API client. See https://www.postman.com/ small_external_link.png

  1. Create the three parameters required in the initial authorization call to WebTitan that are self-generated: state, code_verifier and code_challenge:

  2. Make the oauth2 call to WebTitan to request an access token.

    Format: GET https://your-API-URL.webtitancloud.com:8443/restapi/oauth/authorize

    The following GET and Basic Auth parameters are required to make the call:

    Parameter

    Description

    Example

    response_type

    This is always "code".

    code

    client_id

    This is always "2".

    2

    code_challenge

    An SHA-256 encoded code_verifier (see Step 1).

    9tanTO36l9r-gHOKK6fa_0TzCLMmMA5989OVxEugerQ

    code_challenge_method

    S256

    S256

    state

    This is a self-generated random 40 character string that you create (see Step 1).

    123xkYFwY2qiG7dEb7Cq1z74QNFnmioh5aNcOrRH

    code_verifier

    A self generated 128 character string that you create (see Step 1).

    qJainvnXruMEcECKUTf1Zt4ZnxDN0cw6MV8pXzK1EQ5

    Bze6YOyTyMTuQ3sWm6t0CTpWlNZGHZxvVwz23fsAf

    akVigCVd6jFswK9nbeQ4EuLPvdGvnw5JDmrv2esFu75S

    redirect_uri

    The exact WebTitan URL that you are calling to, with port number, followed by /restapi/oauth/callback

    See WebTitan API URLs to determine your API URL.

    https://your-API-URL.webtitancloud.com:8443/restapi/oauth/callback

    See WebTitan API URLs to determine your API URL.

    code (optional)

    This parameter is only required if 2FA is enabled on your WebTitan. It is the 6 digit code from your authenticator app.

    384 519

    The following Basic Auth parameters must also be passed:

    Parameter

    Description

    Example

    Username

    Your WebTitan username

    admin@yourcompany.com

    Password

    Your WebTitan password

    6*4iw48Xkg3M

    Using the examples above, the complete request looks as follows in Postman:

    WT-API-get-oauth2.jpg

    WT-API-get-oauth2-authorization.jpg

  3. An access token is returned, which displays in Postman as follows below. Select and copy the access token.

    WT-API-access-token.jpg

  4. Once copied, this can then be used for authorization when calling other endpoints. In Postman, this is specified in the Authorization tab as shown below. The token type is Bearer Token.

    WT-API-bearer-token.jpg