Connecting to the API

User Scope

A user can create API keys to read and write to data within the organisation they are a part of.

Generating API Keys

To generate an API Access Token, go here: https://toccata-app.com/org/megacorp/organisation/api-key/create/

Here you can give the API key a name, this will likely be where the API key is going to be used e.g. ‘CI Server’.

You will see a message with your generated API key.

Note: The key, once generated, cannot be viewed again. It is imperative that you store the token somewhere secure and it is advised to only use it for a single integration purpose.

Managing API Keys

To view all previously generated API keys within your organisation, go here: https://toccata-app.com/org/megacorp/organisation/api-key/

This will only show the API key names, not the API keys themselves, we do not save these on our server for security.

You can update the name or revoke an API key by clicking the name of the API key on the API key list page, then clicking the ‘Update API Key’ button.

Calling the API

All Toccata application routes are HATEOAS, meaning the URL in the browser can be used to identify an API endpoint.

When using any API endpoint you must set the HTTP Accept header to ‘application/json’, otherwise you will receive a HTML response and it will just be the login page.

You will also need to add the API Key in the HTTP Authorization header in the format (for example):

Api-Key wKJ74yst.kHZF2wyv3DFc3Juh5GzPZnafuwkOKmk8

For a full specification on the endpoints available please see the API documentation.

GET Requests

GET requests are for reading data from your organisation. So for example, to see the problems within your organisation you can use the following CURL request:

curl -XGET \
    -H 'Authorization: Api-Key <your_api_key>' \
    -H 'Accept: application/json' \
    'https://toccata-app.com/org/megacorp/problem/'

POST Requests

POST requests are for writing data to your organisation. So for example, to create a new problem within your organisation you can use the following CURL request:

curl -X POST \
    -H 'Authorization: Api-Key <your_api_key>' \
    -H 'Accept: application/json' \
    -H "Content-Type: application/json" \
    -d '{"Name": "Test", "Problem Statement": "Test"}' \
    'https://toccata-app.com/org/megacorp/create/'

It is recommended that you use the POST API endpoints with content-type ‘application/json’.