Deep Dive

A technical deeper dive into the Keyfax REST based Web API.

The Keyfax Web API provides a set of secure, stateless HTTP based web services host systems can use to launch Keyfax sessions and obtain results for launched Keyfax sessions when control returns back to the host.

The Keyfax Web API follows RESTful conventions when possible, with most operations performed via GET, POST, PATCH, and DELETE requests on page and database resources. Request and response bodies are encoded as JSON.

To assist with integrations Keyfax exposes the following Web API end points...

• /api/v1/startup - accepts Keyfax start-up data and returns Keyfax launch data

• /api/v1/results - returns results for a Keyfax session given previous Keyfax launch data

• /api/v1/key - programmatically generate or reset your Keyfax Web API keys

• /api/v1/token - programmatically generate JSON Web Tokens (JWT).

These end points are described in further technical detail below. For additional code examples and guidance please also see "Using the Keyfax Web API .NET & JavaScript SDKs".

Getting Started

A host system would typically launch Keyfax to help a tenant or service desk advisor work through a repair request or general enquiry. The host system can be a native desktop application or a web based application.

To assist with different application scenarios Keyfax offers two unique flows to securely make requests into the Keyfax Web API in order to launch Keyfax and obtain Keyfax results. These flows are described in further detail below.

Server Side Flow

We would recommend the server side flow for desktop or server side integrations where it's possible to secure your Keyfax Web API signing key. The typical server side flow is detailed below...

1. Host calls GET /api/v1/key to obtain initial Keyfax Web API keys. Host stores these keys securely locally.

2. Host calls POST /api/v1/startup with valid Keyfax start-up data and a valid Basic authorization schema

3. POST /api/v1/startup responds with launch data you can use to launch a new Keyfax session

4. Host launches Keyfax using the returned launch URL

5. Keyfax completes or cancels and returns to the ReturnUrl if supplied within start-up data

6. Host calls POST /api/v1/results supplying valid launch data and a valid Basic authorization schema

7. POST /api/v1/results responds with results for the completed or cancelled Keyfax session. The host system can then parse or process these results as necessary.

The typical server side flow for launching Keyfax is further illustrated below...

Server Side Flow

If the server side flow seems appropriate for your scenario please considering using the Keyfax Web API .NET SDK.

Client Side Flow

We would recommend the client side flow for web based integrations or for integrations where it's not possible to secure your Keyfax Web API signing key. The client side flow requires an additional step to obtain a JSON Web Token via server side code which can then be to used for subsequent client side requests into the Keyfax Web API.

The basic flow is...

1. Host calls GET /api/v1/key to obtain initial Keyfax Web API keys via server side code. Host stores these keys securely locally. These keys can be used for requests that require our Basic authorization schema.

2. Host calls GET /api/v1/token via server side code supplying a valid Basic authorization schema

3. GET /api/v1/token responds with a JSON Web Token which can be used for subsequent client side requests

4. Client calls POST /api/v1/startup with Keyfax start-up data and a valid JSON Web Token using the Bearer authorization schema

5. POST /api/v1/startup responds with launch data you can use to instantiate a new Keyfax session

6. Client launches Keyfax using the returned launch URL

7. Keyfax completes or cancels and returns to your return URL

8. Client calls POST /api/v1/results supplying launch data and a valid JSON Web Token using the Bearer authorization schema

9. POST /api/v1/results responds with results for the completed or cancelled Keyfax session. The client system can then parse or process these results as necessary.

It's important to note in both our server side and client side flows that step 1 is only necessary to obtain initial Keyfax Web API keys the very first time you use the Keyfax Web API. Once keys have been created and stored locally within the calling system step 1 can be skipped for all subsequent requests.

The typical client side flow for launching Keyfax is further illustrated below...

Client Side Flow

If the client side flow seems appropriate for your scenario please considering using the Keyfax Web API JavaScript SDK.

Verifying Requests

TIP If you are using the provided Web API SDK's you can skip this section. This information is only intended for developers who will be communicating directly with the Keyfax Web API end points and won't be going through the provided Keyfax Web API SDK's. The provided Keyfax Web API SDK's handle concerns such as verifying the request.

The Keyfax Web API uses the authorization header to verify all requests. For verification to succeed you must provide a valid authorization schema via the authorization header within each request into the Keyfax Web API.

The Keyfax Web API supports two authorization schemas - Basic and Bearer. The Basic authorization schema is only intended to be used within server side code where you can ensure your Keyfax Web API signing key is never revealed to end users. The Bearer authorization schema is typically used for client side requests using a JSON Web Token where it's not possible to secure your Keyfax Web API signing key.

As you would expect unlike the Basic authorization schema the Bearer authorization schema does not accept your Keyfax API or signing key and only accepts a JSON Web Token.

Further information on each of these authorization schemas is provided below.

Basic Authentication (Server Side Flow)

The Basic authorization schema is intended to be used within secure server side code where you can ensure your Keyfax Web API signing key is never revealed to end users. The Basic authorization schema should be included within the Authorization header within each request.

The data in the Basic authorization schema will contain the host name, public API key, the request signature (generated from the private signing key), the request time stamp, and a nonce separated by a colon ‘:’. The format for the Basic authorization schema is as follows...

Authorization: Basic {HostName (string)}:{ApiKey (string)}:{RequestSignature (hash)}:{RandomNumber (nonc)}:{Timestamp}

The calling code creates a unique HMAC representing the request originated from it to the server. It does this by combining the request data, signing key, request URI, request content, HTTP method, time stamp, and nonce to produce a unique hash. This unique hash is then base 64 encoded and included as the {RequestSignature} item within the Basic authorization schema as shown above. The calling code sends this hash to Keyfax, along with all information it was going to send already in the request.

Once Keyfax receives the request along with the hash or request signature from the calling code, Keyfax tries to reconstruct the hash by using the received request data from the calling code along with the known signing key, once the hash is generated on the server, the server will be responsible for comparing the hash sent by the calling code with the regenerated one, if they match then Keyfax considers this request authentic and processes the request.

This is by no means an authentication mechanism. The main use for this style of request is to verify the integrity, authenticity, and the identity of the message sender - not for user authentication purposes. The nonce and time stamp are included in creating the signature as well as being sent as plain text values so they can be validated on the server to protect the Keyfax Web API from replay style attacks.

Bearer Authentication (Client Side Flow)

The Bearer authorization schema is typically used for client side requests using a JSON Web Token. Unlike our Basic authorization schema the Bearer authorization schema does not accept your API or signing keys.

This is the preferred authorization schema to use when it's not possible to secure your Keyfax Web API signing key. For example if your making requests via JavaScript you should first make a server side request to GET /api/v1/token supplying your Keyfax Web API keys to obtain a JSON Web Token. This JSON Web Token can then be shared with clients or reflected back to the browser and then used to validate subsequent client side requests into the Keyfax Web API.

The Bearer authorization schema should be included within the Authorization header with each request. The data in the Bearer authorization schema will contain the host name and a base 64 encoded JSON Web Token separated by a colon ‘:’. The format for the Bearer authorization schema is as follows...

Authorization: Bearer {HostName (string)}:{JSONWebToken (string)}

When Keyfax receives a request with a Bearer authorization schema the JSON Web Token supplied with the request will be validated on the server. If validation fails or the token has expired Keyfax will typically return a 401 status code.

Each JSON Web Token contains 3 parts - a header, a payload & a signature. Each piece of the JWT is base-64 encoded separately, and then all three elements are joined by a dot to form a single string. A token’s payload contains a JSON object, and each of the object’s properties is called a claim.

The signature part of a JWT is a Message Authentication Code (or MAC). This signature can only be produced by someone in possession of both the payload (plus the header) and a given secret key. Keyfax uses your signing key as the secret key to validate the JWT MAC. If your signing key changes within Keyfax any previously issued JSON Web Tokens will be invalidated and clients would need to request a new JSON Web Token again via a server side call to GET /api/v1/token.

The JSON Web Token generated by Keyfax is only valid for 24 hours. For long running sessions such as single page applications (SPA's) it can be helpful to generate a new JSON Web Token every few hours. This can be achieved by calling POST /api/v1/token periodically supplying your existing valid JSON Web Token to obtain a new JSON Web Token with a fresh expiry date of 24 hours from the date it was issued.

OpenAPI 2.0 Compliant

The Keyfax Web API conforms to the OpenAPI 2.0 specification. This facilitates the creation of documentation & client / server libraries within various client & server languages.

The OpenAPI 2.0 specification for the Keyfax Web API is available via /interview/docs/v1/swagger when running Keyfax locally.

This resulting specification is provided in JSON format and can be translated with tools such as the Swagger Editor located at https://editor.swagger.io/.

Swagger UI API Explorer

NOTE The Swagger UI API Explorer is only accessible when Keyfax is running locally via localhost or 127.0.0.1. For security reasons this page is not exposed when running Keyfax within a production environment.

Keyfax exposes a Swagger UI based API explorer allowing you to learn & experiment with the Keyfax Web API. You can see an example of this API explorer below...

Swagger UI API Explorer

The Swagger UI API Explorer is available via /interview/swagger/index when running Keyfax locally. Further information on each of these end points is also provided below.

GET /api/v1/startup

This method returns example start-up data. You can POST the returned example start-up data to this same end point to generate launch data for Keyfax. It's important to remember you will need to customize the example start-up data to work within your integration. The example start-up data returned from this end point is only provided for convenience whilst developing and should not be used for real world production environments.

Verification

A authorization header with a valid Basic or Bearer schema is required to authenticate with this method.

Request Data

No request data is necessary for this request.

Response Body

This end point will return example start-up data for the currently defined master configuration within kfServerConfig.xml. An example of the start-up data schema is shown below...

{
  "originatingSystem": {
    "key": "string",
    "id": "string",
    "value": "string",
    "attributes": [
      {}
    ],
    "children": [
      {}
    ]
  },
  "guid": {
    "key": "string",
    "id": "string",
    "value": "string",
    "attributes": [
      {}
    ],
    "children": [
      {}
    ]
  },
  "originatingGuid": {
    "key": "string",
    "id": "string",
    "value": "string",
    "attributes": [
      {}
    ],
    "children": [
      {}
    ]
  },
  "mode": {
    "key": "string",
    "id": "string",
    "value": "string",
    "attributes": [
      {}
    ],
    "children": [
      {}
    ]
  },
  "userName": {
    "key": "string",
    "id": "string",
    "value": "string",
    "attributes": [
      {}
    ],
    "children": [
      {}
    ]
  },
  "password": {
    "key": "string",
    "id": "string",
    "value": "string",
    "attributes": [
      {}
    ],
    "children": [
      {}
    ]
  },
  "company": {
    "key": "string",
    "id": "string",
    "value": "string",
    "attributes": [
      {}
    ],
    "children": [
      {}
    ]
  },
  "clientId": {
    "key": "string",
    "id": "string",
    "value": "string",
    "attributes": [
      {}
    ],
    "children": [
      {}
    ]
  },
  "scriptSet": {
    "key": "string",
    "id": "string",
    "value": "string",
    "attributes": [
      {}
    ],
    "children": [
      {}
    ]
  },
  "category": {
    "key": "string",
    "id": "string",
    "value": "string",
    "attributes": [
      {}
    ],
    "children": [
      {}
    ]
  },
  "topic": {
    "key": "string",
    "id": "string",
    "value": "string",
    "attributes": [
      {}
    ],
    "children": [
      {}
    ]
  },
  "returnUrl": {
    "key": "string",
    "id": "string",
    "value": "string",
    "attributes": [
      {}
    ],
    "children": [
      {}
    ]
  },
  "callerDetails": {
    "key": "string",
    "id": "string",
    "value": "string",
    "attributes": [
      {}
    ],
    "children": [
      {}
    ]
  },
  "tenancyDetails": {
    "key": "string",
    "id": "string",
    "value": "string",
    "attributes": [
      {}
    ],
    "children": [
      {}
    ]
  },
  "propertyId": {
    "key": "string",
    "id": "string",
    "value": "string",
    "attributes": [
      {}
    ],
    "children": [
      {}
    ]
  },
  "property ": {
    "key": "string",
    "id": "string",
    "value": "string",
    "attributes": [
      {}
    ],
    "children": [
      {}
    ]
  },
  "rolDetail": {
    "key": "string",
    "id": "string",
    "value": "string",
    "attributes": [
      {}
    ],
    "children": [
      {}
    ]
  },
  "customData": {
    "key": "string",
    "id": "string",
    "value": "string",
    "attributes": [
      {}
    ],
    "children": [
      {}
    ]
  }
}

Content Types

The request data and response body can represented as JSON or XML depending on the Accept and Content-Type headers sent with this request.

Response 200

A 200 status code indicates example start-up data has been returned successfully.

Response 401

A 401 status code indicates the supplied authorization header was not valid. Further information on the nature of the error will be provided within the response body.

POST /api/v1/startup

This method accepts start-up data & returns launch data to instantiate a Keyfax session. The start-up data can be posted within the request body and can be represented as either JSON or XML. Use this end points GET method to obtain example start-up data you can POST to this method. Within the returned launch data a launch URL will be provided which you can use to launch a Keyfax session. The launch data will also contain a unique GUIDwhich you can use later to obtain results for the launched session within your integration.

Verification

A authorization header with a valid Basic or Bearer schema is required to authenticate with this method.

Request Data

The JSON below represents the start-up data you would supply to the POST method via the request body.

{
  "mode": {
    "value": "ROL"
  },
  "userName": {
    "value": "administrator"
  },
  "password": {
    "value": "xxx"
  },
  "company": {
    "value": "OL3_Dev"
  },
  "scriptSet": {
    "value": "ROL"
  },
  "returnUrl": {
    "value": "https://hostsystem.com/KeyfaxComplete.aspx?status=0&co=1&guid=2&user=3"
  }
}

Response Body

Taking the example request data the JSON below represents a typical successful response from this method.

{
  "guid": "55079032-6082-4fd3-af59-4cf3a1f701cb",
  "launchUrl": "https://keyfaxurl.com/InterView/OL3/Main.aspx?co=OL3_Dev&guid=55079032-6082-4fd3-af59-4cf3a1f701cb",
  "company": "RDFL_Dev"
}

Content Types

The request data and response body can represented as JSON or XML depending on the Accept and Content-Type headers sent with this request.

Response 200

A 200 status code indicates start-up data was processed and launch data has been returned successfully.

Response 401

A 401 status code indicates the supplied authorization header was not valid. Further information on the nature of the error will be provided within the response body.

Response 500

A 500 status code indicates the supplied start-up data was invalid or a problem occurred launching the session. Further information on the nature of any error will be available within the response body.

POST /api/v1/results

Return results for the instantiated session within Keyfax. Results are only available after a Keyfax session has been started and the session has been completed or canceled by the user.

Verification

A authorization header with a valid Basic or Bearer schema is required to authenticate with this method.

Request Data

The JSON below represents the typical request data sent to this method.

{
  "company": "OL3_Dev",
  "guid": "55079032-6082-4fd3-af59-4cf3a1f701cb"
}

The company and guid values are returned as part of the launch data when you post initial start-up data to POST /api/v1/startup.

Response Body

The JSON below represents a typical response from this method.

{
  "KeyfaxData": {
    "Call": {
      "@name": "Call1",
      "@type": "ROL",
      "OriginatingSystem": "TemplateLogin",
      "Company": "OL3_Dev",
      "CategoryId": "24684",
      "CategoryText": "Baths, Basins, Sinks",
      "TopicId": "28769",
      "TopicText": "Basin",
      "CallText": "Basin",
      "LogDate": "24/03/2021 16:20:39",
      "UserCode": "administrator",
      "ScriptPath": {
        "#cdata-section": "html|Example System Start Up Script Set a system priority\\n|html|Insurance System Question <b>Option 2</b><br />|html|Where is it? <b>in the bathroom</b><br />|html|What is the problem? <b>basin loose</b><br />|html|Is it in danger of falling off? <b>Yes</b><br />|html|What type of basin is it? <b>on a pedestal</b>|"
      },
      "ExpenditureCode": null,
      "ContractCode": null,
      "PreAuthoriseRequired": null,
      "ReasonCode": "",
      "ReasonText": "",
      "Recharge": "0",
      "RechargeCode": "RREP",
      "RechargeCost": "102.44",
      "ScheduleId": "administrator\\10",
      "SiteVisit": "test",
      "AdditionalInfo": "test",
      "SpecialInstructions": "",
      "RepairCount": "2",
      "AdviceCount": "0",
      "ActionCount": "0",
      "SubActionCount": "0",
      "Repair": [
        {
          "@name": "Repair1",
          "CompleteBy": "24/03/2021 16:20:39",
          "ResponseDays": "0",
          "Priority": "ISUR1",
          "PriorityId": "40770",
          "RepairCode": "SYSS1",
          "RepairCodeDesc": "Sys Priority Service",
          "UnitOfMeasure": "IT",
          "UnitOfMeasureQuantity": "1",
          "Contractor": ""
        },
        {
          "@name": "Repair2",
          "CompleteBy": "29/03/2021 16:20:39",
          "ResponseDays": "5",
          "Priority": "U",
          "PriorityId": "26059",
          "RepairCode": "630713",
          "RepairCodeDesc": "BASIN:REFIX WASH HAND BASIN",
          "UnitOfMeasure": "NO",
          "UnitOfMeasureQuantity": "1",
          "Contractor": ""
        }
      ]
    },   
    "Status": "1",
    "GUID": "55079032-6082-4fd3-af59-4cf3a1f701cb"
  }
}

Content Types

The request data and response body can represented as JSON or XML depending on the Accept and Content-Type headers sent with this request.

Response 200

A 200 status code indicates Keyfax results have returned successfully. This indicates the session was completed or cancelled. See the results for further details on the session.

Response 202

A 202 status code indicates the Keyfax session has been launched but the session has not been completed or cancelled yet so no results are available.

Response 401

A 401 status code indicates the supplied authorization header was not valid. Further information on the nature of the error will be provided within the response body.

Response 500

A 500 status code indicates an exception occurred either parsing the supplied data or generating the response. Further information on the nature of any error will be available within the response body.

GET /api/v1/key

This end point can be accessed anonymously without verification and is intended to generate an initial API & signing key for use with the Keyfax Web API. The initial keys will only be returned via this end point if no existing Web API keys exist. If existing keys exist this end point will return a 400 Bad Request response. To generate additional keys you can use the initial keys and perform a POST request to this same end point to generate additional Web API keys for the authenticated host name.

Verification

This end point does not require any verification but will only work for the very first request for any given host name and the supplied host name must be defined via the kfServerConfig.xml file.

Request Data

No request data is necessary for this request.

Response Body

The JSON below represents a typical response from this method.

{
	"apiKey":"28f7d828-3f78-4482-a0ac-5f5a64edd4b4",
	"signingKey":"EI4fm9mmaLttvt5485x+YfOBNYKbb++cYG5HH/aZ8VfT2SdXLwrKHjKqCjckTsovVyoUm1x0CrMRM/wDFc1LTw==",
	"schemaName":"Basic",
	"hostName":"Dev"
}

Content Types

The request data and response body can represented as JSON or XML depending on the Accept and Content-Type headers sent with this request.

Response 201

A 201 status code indicates a new Keyfax Web API key has been created successfully.

Response 400

A 400 status code indicates keys already exist for the supplied host name and an initial key cannot be created.

Response 500

A 500 status code indicates an exception occurred generating the initial API keys. Further information on the nature of any error will be available within the response body.

POST /api/v1/key

If you believe your signing key has been compromised you can call this end point to generate new API keys within Keyfax. This end point will only return the new API key within it's response. The new signing key (and API key) will only be sent to the approved delivery mechanism defined within the Keyfax KfServerConfig.xml file for the host name supplied within the authorization schema.

Keyfax supports 2 delivery mechanisms for informing host systems of Web API key changes. As an integrator you can choose to send any new keys via email or post any new API keys to a web hook URL to automate the key reset process.

The delivery mechanism used for the host name supplied with the request can be found within kfServerConfig.xml within the Keyfax web application. This element is shown below. Multiple KeyGen elements are supported with unique host names...

<KFServerConfig>
	<WebApi>
		<!-- The default host is used if the host name supplied with an API request was not found within kfServerConfig.xml -->
		<KeyGen hostName="Default" WebHookUrl="http://hostsystem.com/KeyfaxApiWebHook.aspx" Email="[e-mail]"/>
	</WebApi>
</KFServerConfig>

Taking the example above if we are using "Default" as the host name within the authorization schema whenever POST /api/v1/key is called the newly generated API and signing key for the "Default" host will be posted to http://hostsystem.com/KeyfaxApiWebHook.aspx and also sent via email to [e-mail].

If both a web hook URL and email address are defined the new signing key will be posted to the defined web hook URL and also sent to the defined email address. You can leave the WebHookUrl and Email attributes shown above empty to skip calling a web hook or sending new keys via email.

Resetting Keys via Email

1. Call POST /api/v1/key supplying a valid Basic authorization schema within the authorization header.

2. If verification is successful and an email address is present within the kfServerConfig.xml file for the supplied host Keyfax will generate and save a new API & signing key

3. Keyfax will respond with the new API key. The new signing key will be sent via email to the email address defined within kfServerConfig.xml.

Resetting Keys via a Web Hook

If a web hook URL is defined within the kfServerConfig.xml file matching the authenticated host name newly generated API and signing keys will be posted as a JSON object to the web hook URL. The basic steps are...

1. Call POST api/v1/key supplying a valid Basic authorization schema within the authorization header.

2. If authorization is successful and a web hook URL is defined within the kfServerConfig.xml file within the WebApi/KeyGen element with a host name attribute matching the authenticated host name Keyfax will post the new keys to the web hook URL.

3. Keyfax will respond with the new API key. The new signing key will only be sent to the web hook URL defined within kfServerConfig.xml.

Verification

A authorization header with a valid Basic authorization schema is required to authenticate with this method.

Request Data

No request data is necessary for this request.

Response Body

The JSON below represents a typical response from this method.

{
    "apiKey": "string"
}

Content Types

The request data and response body can represented as JSON or XML depending on the Accept and Content-Type headers sent with this request.

Response 200

A 200 status code indicates the signed key was accepted and the Keyfax API key has been reset successfully.

Response 401

A 401 status code indicates the supplied authorization header was not valid. Further information on the nature of the error will be provided within the response body.

Response 500

A 500 status code indicates the key could not be created or a problem occurred communicating with the host.

Reset Methods

Email Address

When Keyfax receives a valid API key reset request via POST /api/v1/key if a approved, white-listed email address is defined within kfServerConfig.xml for the supplied host name Keyfax will generate a new API & signing key for that host name and will send both keys via email to the defined email address within kfServerConfig.xml. The will require manual intervention and you will need to take these new keys and plug them into your existing integrations calling the Keyfax Web API.

You can see an example of the generated email below...

Web API keys provided via email

Web Hook URL

Whilst this method requires additional set-up ahead of time using a web hook to reset your Keyfax API keys once set-up allows for automation of this process with no intervention from end users or developers.

When Keyfax receives a valid API key reset request via POST /api/v1/key if a web hook URL is defined within kfServerconfig.xml Keyfax with generate a new API & signing key and will post these keys to the configured web hook URL via the POST method with the following request body...

{
	"apiKey":"28f7d828-3f78-4482-a0ac-5f5a64edd4b4",
	"signingKey":"EI4fm9mmaLttvt5485x+YfOBNYKbb++cYG5HH/aZ8VfT2SdXLwrKHjKqCjckTsovVyoUm1x0CrMRM/wDFc1LTw==",
	"schemaName":"Basic",
	"hostName":"Default"
}

When your web hook URL receives this request you can take the sent keys and update these within your host systems local key store. The host system can then use these new keys for subsequent requests.

When are the Keyfax Web API Keys actually reset?

It's important to note that a successful request to POST /api/v1/key will only generate new Keyfax API keys for the host name supplied within the authorization header and will not immediately expire or invalidate existing keys for the supplied host name.

Only once a request comes into the Keyfax Web API using the newly generated keys for the host name will the current or existing keys be invalidated for the host name and all subsequent requests will require the new API keys to be used.

GET /api/v1/token

This end point generates a JSON Web Token. This is used to verify client side requests into the Keyfax Web API. The generated JSON Web Token is signed using your private Keyfax signing key and contains your public API key as a claim to further verify requests. This method can only be called using Basic authentication as this method is typically called from server side code where you can secure your private Keyfax Web API signing key.

The generated JSON Web Token will be valid for 24 hours after creation. For long running sessions you should use the JSON Web Token generated by this GET method to periodically call POST /api/v1/token to renew or generate additional JSON Web Tokens for long running client sessions.

Verification

A authorization header with a valid Basic authorization schema is required to authenticate with this method.

Request Data

No request data is necessary for this request.

Response Body

The JSON below represents a typical response from this method.

{
  "company": "string",
  "token": "string"
}

Content Types

The request data and response body can represented as JSON or XML depending on the Accept and Content-Type headers sent with this request.

Response 200

A 200 status code indicates the token was returned successfully.

Response 401

A 401 status code indicates the supplied authorization header was not valid. Further information on the nature of the error will be provided within the response body.

Response 500

A 500 status code indicates an exception occurred generating the token. Further information on the nature of any error will be available within the response body.

POST /api/v1/token

Requires an existing valid JSON Web Token for verification purposes. If verification is successful this end point will generate a new JSON Web Token which will expire again within 24 hours. The resulting JWT is derived from the current active API & signing keys used for server side Basic authentication.

To obtain a JWT for the first time you must make a request to GET /api/v1/token using server side code supplying a valid Basic authorization header. Once the server has issued an initial JWT this can then be used on clients for subsequent API requests or to periodically renew the JWT for longer running client sessions using this end point.

Verification

A authorization header with a valid Bearer authorization schema is required to authenticate with this method.

Request Data

No request data is necessary for this request.

Response Body

The JSON below represents a typical response from this method. The token property would be populated with the newly generated JSON Web Token.

{
  "company": "string",
  "token": "string"
}

Content Types

The request data and response body can represented as JSON or XML depending on the Accept and Content-Type headers sent with this request.

Response 200

A 200 status code indicates the token was returned successfully.

Response 401

A 401 status code indicates the supplied authorization header was not valid. Further information on the nature of the error will be provided within the response body.

Response 404

A 404 status code indicates no active key for the Basic authorization schema exist matching the supplied host name within the Bearer authorization schema for this request.

Response 500

A 500 status code indicates an exception occurred generating the token. Further information on the nature of any error will be available within the response body.

API Versioning

Versioning is only for backwards incompatible changes For new features and additions to the API, such as adding a new API endpoint, or including a new object in an existing API endpoint's response, there won't be a new version. You'll be able to take advantage of any new functionality on the version of the API you're currently using.

The Keyfax Web API is versioned. A new API version is released when we introduce a backwards-incompatible change to the API. For example, changing a property name or object design. All versioning is controlled via the URI used to access the Keyfax Web API. Each API request should contain the version of the API end point to use within the URI. This is typically in the form /api/{version}/endpoint - or /api/v1/token, /api/v2/token etc. You can explore documentation for each available version of the Keyfax Web API via the Swagger UI API explorer provided within the Keyfax web application.

The Keyfax Web API SDK's

We would suggest whenever possible leveraging the provided Keyfax Web API SDK's to ease development. Further information on these SDK's can be found via the link below.

• See Using the Keyfax Web API .NET & JavaScript SDKs

Additional Tools & Resources

To further explore the Keyfax Web API you can open the swagger.json or swagger.yaml specification available at /Interview/docs/v1/swagger within tools such as Swagger Editor (https://editor.swagger.io/) or ApiMatic (https://www.apimatic.io/ - requires account).

Known Errors & Issues

When working with the Keyfax Web API you may encounter one or more of the following errors or warnings. These errors or warnings typically indicate Keyfax is not configured correctly.

A master configuration has not been defined within KFServerConfig.xml. Please ensure a master="1" attribute is specified on the KFConfigs/ServiceArea/Config element you wish to be the master configuration.

You may see this message when attempting to use the Keyfax Web API if no configuration has been defined as the master configuration within kfServerConfig.xml. You should contact Omfax support to assist with this issue.

An error occurred sending the request or The supplied URL is not valid and cannot be converted to a System.Uri type. The supplied URL must be a valid absolute URL

If you see this message please ensure the URL being used to communicate with the Keyfax Web API end points is correct. If you are using our .NET or JavaScript SDK clients you'll need to provide a valid base URL matching your Keyfax web application address. For example https://yourkeyfaxurl.com/inteview or http://localhost:8080/interview/ etc.