The below documentation is created programmatically using the Keyfax Web API OpenAPI specification. For more detailed examples on how to call each of these API end-points please see our Web API Quick Start and Deep Dive guides.
Obtaining a Keyfax Launch URL
Use these end-points to post start-up data and obtain a Keyfax launch URL.
Processing Keyfax Results
Use this end point to obtain Keyfax results.
Obtaining API keys
Use these end-points to generate API keys for our Basic or API Key verification methods.
Bearer / JWT Tokens
Use these end-points to obtain a short-lived JSON Web Token (JWT) for Bearer verification.
Returns example start-up data used to generate launch data for Keyfax.
get
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 likely need to customize the example start-up data to correctly work within your environment. The example data is only provided for convenience.
Header parameters
AuthorizationstringOptional
A valid bearer authorization schema. For example "Bearer {hostName}:{jsonWebToken}". Please refer to Keyfax Web API documentation for assistance or use the Keyfax Web API .NET or JavaScript SDK.
Responses
200
A 200 status code indicates example start-up data has been returned successfully.
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.
get
GET /interview/api/v1/startup HTTP/1.1
Host: localhost:8088
Accept: */*
Provides a mechanism for hosts to generate an initial Keyfax Web API key.
get
This end point can be accessed anonymously without authentication and is intended to generate initial keys for use with the Keyfax Web API. The initial key will only be returned via this end point if no existing Web API keys exist for the supplied host name. The supplied host name must also first be defined via the WebApi/KeyGen element within kfServerConfig.xml before keys can be generated. 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.
Query parameters
hostNamestringRequired
The name of the host to create the keys for - i.e. DEV, LIVE, TEST etc. To ensure new keys can be sent correctly ensure the kfServerConfig.xml file contains a WebApi/KeyGen element with a matching host name attribute.
Responses
201
A 201 status code indicates a new Keyfax Web API key has been created successfully.
400
A 400 status code indicates keys already exist for the supplied host name or the host name has not been defined within the kfServerConfig.xml file.
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.
get
GET /interview/api/v1/key HTTP/1.1
Host: localhost:8088
Accept: */*
Provides a secure mechanism to programmatically reset your Keyfax API keys.
post
If you believe your Keyfax Web API keys have been compromised you can call this end point to generate new API keys within Keyfax. An authenticated POST request to this end point will generate new API keys within Keyfax. This end point will only return the new API key. The new signing key will be sent along with the new API key to the white-listed delivery mechanism defined within your Keyfax KfServerConfig.xml file.
If a web hook URL is defined within configuration the new keys will be posted as a {Keyfax.WebApi.Sdk.Basic.v1.Models.KeyResult} JSON object to the defined web hook URL. If an email address is defined the signing key will be sent to the defined email address. If both a web hook URL and email address are defined the signing key will be posted to the defined web hook URL and also sent to the defined email address.
The web hook URL and / or email address delivery mechanisms are defined via the WebApi/KeyGen element within your Keyfax KfServerConfig.xml file.
Header parameters
AuthorizationstringRequired
A valid basic authorization schema. For example "Basic {hostName}:{apiKey}:{requestSignature}:{nonce}:{timeStamp}". Please refer to Keyfax Web API documentation for assistance or use the Keyfax Web API .NET or JavaScript SDK.
Responses
201
A 201 status code indicates a new Keyfax Web API key has been created successfully. Any existing keys will continue to work until the new key is used for the first time.
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.
500
A 500 status code indicates an exception occurred resetting the API keys. Further information on the nature of any error will be available within the response body.
post
POST /interview/api/v1/key HTTP/1.1
Host: localhost:8088
Authorization: text
Accept: */*
Deletes the basic authentication keys for the specified host name.
delete
Query parameters
hostNamestringRequired
The name of the host to delete the keys for - i.e. DEV, LIVE, TEST etc. To ensure new keys can be deleted ensure the kfServerConfig.xml file contains a WebApi/KeyGen element with a matching host name attribute.
Header parameters
AuthorizationstringRequired
A valid basic authorization schema. For example "Basic {hostName}:{apiKey}:{requestSignature}:{nonce}:{timeStamp}". Please refer to Keyfax Web API documentation for assistance or use the Keyfax Web API .NET or JavaScript SDK.
Responses
200
A 200 status code indicates a the keys matching the supplied host name have been deleted successfully. Any existing keys will continue to work until the new key is used for the first time.
Responseobject
304
A 304 status code indicates the supplied host name was not found within the Keyfax database.
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.
500
A 500 status code indicates an exception occurred deleting the API keys. Further information on the nature of any error will be available within the response body.
delete
DELETE /interview/api/v1/key HTTP/1.1
Host: localhost:8088
Authorization: text
Accept: */*
{}
Generates a JSON Web Token / JWT for client side authentication purposes.
get
The generated JSON Web Token is signed using your Keyfax private API 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 were you can secure your Keyfax Web API signing key.
The generated JSON Web Token will be valid for 24 hours after creation by default. 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.
Header parameters
AuthorizationstringRequired
A valid basic authorization schema. For example "Basic {hostName}:{apiKey}:{requestSignature}:{nonce}:{timeStamp}". Please refer to Keyfax Web API documentation for assistance or use the Keyfax Web API .NET or JavaScript SDK.
Responses
200
A 200 status code indicates the token was returned successfully.
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.
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.
get
GET /interview/api/v1/token HTTP/1.1
Host: localhost:8088
Authorization: text
Accept: */*
{
"company": "text",
"token": "text"
}
Renews a JSON Web Token / JWT for client side authentication purposes given an existing valid JWT.
post
Requires an existing valid JSON Web Token for authentication purposes. If authentication 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 GET request to /api/v1/token using server side authentication 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 long running sessions using this end point.
Header parameters
AuthorizationstringRequired
A valid bearer authorization schema. For example "Bearer {hostName}:{jsonWebToken}". Please refer to Keyfax Web API documentation for assistance or use the Keyfax Web API .NET or JavaScript SDK.
Responses
200
A 200 status code indicates the token was returned successfully.
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.
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. Ensure a API & signing key have been generated within Keyfax for the supplied host name.
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
POST /interview/api/v1/token HTTP/1.1
Host: localhost:8088
Authorization: text
Accept: */*
Generate the launch data required to instantiate a Keyfax session.
post
This method accepts start-up 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.
Header parameters
AuthorizationstringOptional
A valid bearer authorization schema. For example "Bearer {hostName}:{jsonWebToken}". Please refer to Keyfax Web API documentation for assistance or use the Keyfax Web API .NET or JavaScript SDK.
Body
startUpXmlstringOptional
Responses
200
A 200 status code indicates start-up data was processed and launch data has been returned successfully.
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.
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 launch data to return results for the instantiated session within Keyfax.
post
Returns script results for a given session. Results are only available after a Keyfax session has been started and the session has been completed or canceled.
Header parameters
AuthorizationstringOptional
A valid bearer authorization schema. For example "Bearer {hostName}:{jsonWebToken}". Please refer to Keyfax Web API documentation for assistance or use the Keyfax Web API .NET or JavaScript SDK.
Body
guidstringOptional
launchUrlstringOptional
companystringOptional
Responses
200
A 200 status code indicates Keyfax results have returned successfully. This indicates the session was completed or canceled. See the results for further details on the session.
Responseobject
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.
422
A 422 status code indicates the Keyfax session has not been launched, completed or canceled yet so no results are available. Further details on the status of the session will be provided within the response body.
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.
